Google Gmail API
Browse all Google APIs✓ Official Vendor SpecCommunicationsEmail Deliveryoauth279 EndpointsREST
For Agents
Send emails, read inbox messages, manage drafts and labels, and search mailbox content across Gmail accounts. Supports 79 operations covering threads, attachments, and push notification watches.
Use for: I need to send an email with attachments through Gmail, Search for all emails from a specific sender in the last week, I want to create a draft email and send it later, List all unread messages in a user's inbox
Not supported: Does not handle calendar scheduling, file storage, or video conferencing — use for email messaging and mailbox management only.
Send, receive, and organize email programmatically through Gmail mailboxes with support for threads, labels, drafts, and push notifications. Access 1.8 billion Gmail accounts' messaging infrastructure including attachment handling, search filtering, and real-time change notifications via pub/sub watches. Supports batch operations for bulk message management and granular OAuth scopes for least-privilege access control.
Install Jentic One Beta
Connect the Gmail API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Gmail API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Gmail API.
Send transactional and notification emails with attachments and inline images
Search mailbox content using Gmail's query syntax with label, date, and sender filters
Organize messages into threads and apply custom labels for automated triage
Watch for new messages in real time via pub/sub push notifications
Compose and schedule drafts before sending on behalf of users
Export and import mailbox data with batch delete and batch modify operations
Retrieve message metadata and full MIME content for parsing and analysis
Use Cases
Patterns agents use Gmail API for, with concrete tasks.
★ AI Agent Email Automation
AI agents use the Gmail API through Jentic to send automated responses, parse incoming messages for actionable data, and route emails based on content analysis. An agent searches Jentic for 'send an email via Gmail,' receives the operation schema, and executes the send with proper MIME formatting — no manual OAuth configuration required. Handles up to 2,000 messages per user per day within Gmail's sending limits.
Send an email to support@example.com with subject 'Order Confirmation #12345' and HTML body containing order details, then verify the message appears in the Sent folder
Inbox Monitoring and Triage
Set up real-time push notifications to monitor Gmail inboxes for new messages matching specific criteria, then automatically apply labels, forward, or extract structured data. The Gmail API's watch endpoint delivers change notifications via Google Cloud Pub/Sub, enabling event-driven workflows without polling. Supports filtering by label, sender, subject, and date range across the full mailbox history.
Set up a watch on the user's inbox using POST /gmail/v1/users/me/watch with topicName pointing to a Pub/Sub topic, then list the 5 most recent unread messages
Email Search and Data Extraction
Query Gmail mailboxes using the same search syntax available in the Gmail web interface to find messages by sender, date, label, attachment type, or content keywords. Extract structured data from message bodies, headers, and attachments for downstream processing. The API returns full MIME message content including all parts and encoded attachments, enabling complete email parsing.
Search for all messages matching the query 'from:billing@vendor.com has:attachment after:2024/01/01' and retrieve the attachment content from the first matching message
Draft Management and Scheduled Sending
Create, update, and send email drafts programmatically to support approval workflows, scheduled communications, and template-based messaging. The Gmail API supports full MIME message construction in drafts including To, CC, BCC, reply headers, and rich HTML formatting. Drafts sync across all Gmail clients instantly, enabling hybrid human-AI email composition workflows.
Create a draft email with subject 'Weekly Report' addressed to team@company.com with HTML body, then retrieve the draft ID and send it using POST /gmail/v1/users/me/drafts/send
Key Endpoints
79 endpoints — send, receive, and organize email programmatically through gmail mailboxes with support for threads, labels, drafts, and push notifications.
METHOD
PATH
DESCRIPTION
POST
/gmail/v1/users/{userId}/messages/send
Send an email message
GET
/gmail/v1/users/{userId}/messages
List messages in the mailbox
GET
/gmail/v1/users/{userId}/messages/{id}
Get a specific message by ID
POST
/gmail/v1/users/{userId}/drafts
Create a new draft
POST
/gmail/v1/users/{userId}/drafts/send
Send an existing draft
POST
/gmail/v1/users/{userId}/watch
Set up push notification watch
GET
/gmail/v1/users/{userId}/threads
List email threads
POST
/gmail/v1/users/{userId}/labels
Create a new label
POST
/gmail/v1/users/{userId}/messages/send
Send an email message
GET
/gmail/v1/users/{userId}/messages
List messages in the mailbox
GET
/gmail/v1/users/{userId}/messages/{id}
Get a specific message by ID
POST
/gmail/v1/users/{userId}/drafts
Create a new draft
POST
/gmail/v1/users/{userId}/drafts/send
Send an existing draft
POST
/gmail/v1/users/{userId}/watch
Set up push notification watch
GET
/gmail/v1/users/{userId}/threads
List email threads
POST
/gmail/v1/users/{userId}/labels
Create a new label
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
Gmail OAuth 2.0 tokens with granular scopes are stored encrypted in the Jentic vault (MAXsystem). Agents receive scoped access tokens — raw OAuth credentials and refresh tokens never enter the agent's context. Supports per-scope isolation so an agent sending emails cannot read inbox content.
Intent-based discovery
Agents search by intent (e.g., 'send an email via Gmail' or 'read unread messages') and Jentic returns matching Gmail operations with their input schemas, OAuth scope requirements, and MIME format specifications, so the agent can execute the right endpoint without parsing Google's API documentation.
Time to first call
Direct Gmail integration: 3-7 days for OAuth consent screen setup, token management, MIME encoding, and error handling. Through Jentic: under 1 hour — search for the operation, load the schema, execute with proper auth handled automatically.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Gmail API through Jentic.
What authentication does the Gmail API use?
The Gmail API uses OAuth 2.0 with granular scopes ranging from read-only access (gmail.readonly) to full mailbox control (mail.google.com). Through Jentic, OAuth tokens are stored in the MAXsystem vault and agents receive scoped access tokens, so raw credentials never enter the agent's context. You can start with restricted scopes like gmail.send for send-only access.
Can I search emails by sender, date, and label with the Gmail API?
Yes, the GET /gmail/v1/users/{userId}/messages endpoint accepts a 'q' parameter using the same query syntax as the Gmail search box. You can combine operators like 'from:sender@example.com after:2024/01/01 label:inbox has:attachment' to filter messages precisely. Results return message IDs that you then fetch individually for full content.
What are the rate limits for the Gmail API?
The Gmail API enforces a per-user sending limit of 2,000 messages per day for Google Workspace accounts (500 for free Gmail accounts). API calls are limited to 250 quota units per user per second. Batch operations like batchDelete and batchModify count as single API calls but are limited to 1,000 message IDs per request.
How do I set up real-time email notifications with the Gmail API through Jentic?
Use Jentic to search for 'watch gmail inbox for new messages,' then execute the POST /gmail/v1/users/{userId}/watch endpoint with a Google Cloud Pub/Sub topic name. The watch delivers push notifications for 7 days before requiring renewal. Install Jentic with pip install jentic, authenticate at https://app.jentic.com/sign-up, and search for the watch operation to get the full schema.
Is the Gmail API free to use?
The Gmail API itself is free — there are no per-call charges. You need a Google Cloud project with the Gmail API enabled. Usage is governed by quota limits (250 units/second per user) rather than pricing tiers. Google Workspace accounts get higher sending limits than free Gmail accounts.
Can I send emails with attachments using the Gmail API?
Yes, use the POST /gmail/v1/users/{userId}/messages/send endpoint with a multipart MIME message body. Attachments are base64url-encoded in the MIME payload. The API supports attachments up to 25 MB for regular sends and up to 35 MB when using the upload endpoint with resumable upload protocol.
How do I read full email content including HTML and attachments?
Call GET /gmail/v1/users/{userId}/messages/{id} with format=full to receive the complete MIME structure. The response includes all message parts (text/plain, text/html) and attachment metadata. For large attachments, use the separate GET /gmail/v1/users/{userId}/messages/{id}/attachments/{attachmentId} endpoint to download attachment data.
GET STARTED