canonical: https://jentic.com/apis/googleapis.com/gmail

# Google Gmail API

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.

## For AI 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.

## Scope

Does not handle calendar scheduling, file storage, or video conferencing - use for email messaging and mailbox management only.

## Capabilities

- 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

### 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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

| 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 |

## Key resources

- **Messages** — Send, read, trash, delete, and batch modify email messages with full MIME content access
- **Threads** — Retrieve and modify conversation threads grouping related messages
- **Labels** — Create, update, and delete labels for organizing messages
- **Drafts** — Create, update, list, delete, and send draft messages
- **History** — List mailbox change history for incremental sync
- **Settings** — Manage filters, forwarding rules, IMAP/POP settings, and send-as aliases

## Why Jentic

- **Setup:** Wiring the Gmail API by hand means setting up Google OAuth 2.0 with granular per-scope consent, refreshing short-lived access tokens, and assembling MIME messages yourself. Through Jentic you install once, import the Gmail API from the API Directory, store the OAuth credential once, and your agent calls it.
- **Permission scoping:** The Gmail API addresses the authenticated user's own mailbox, so scope the agent to the operations it needs, such as sending a message or listing threads. You choose that operation set, so label creation or a watch is not included unless you add them.
- **Credential handling:** Your Gmail OAuth credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'send an email via Gmail' or 'read unread messages', and Jentic returns the matching Gmail operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **SendGrid Mail API** — Dedicated transactional email delivery service with deliverability optimization and analytics
- **Mailchimp API** — Email marketing platform with campaign management, audience segmentation, and analytics
- **Google Calendar API** — Schedule meetings and manage events referenced in email communications
- **Slack API** — Team messaging platform for real-time communication alongside email workflows

## FAQ

### 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 your Jentic One instance 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 through Jentic One, the self-hosted execution layer, 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.

### Can I limit what my agent is allowed to do with the Gmail API?

Yes. Because Jentic One is self-hosted, you decide which Gmail operations your agent may call and which OAuth credential it uses, and the Gmail API only ever addresses the authenticated user's own mailbox. You can scope the agent to just the operations it needs, such as sending a message or listing threads, so higher-impact actions like creating labels or setting up a watch stay off unless you explicitly add them. Your OAuth credential is stored once by your own Jentic One instance and injected at execution time, so it never enters the agent's prompt or context.