--- title: Gmail API Integration on Truto slug: gmail category: Email canonical: "https://truto.one/integrations/detail/gmail/" --- # Gmail API Integration on Truto **Category:** Email **Status:** Generally available ## Unified APIs ### Unified Emails API - **Attachments** — Attachments are the files associated with an email. - **Emails** — An email is a digital message sent and received electronically over the Internet. It typically contains a subject, sender, recipients, body content, and sometimes attachments. - **Folders** — The folder is a container used to organize and manage email messages. - **Mailboxes** — - **Organizations** — - **Users** — Users represent the people using the underlying emails system. They are usually called agents, team members, admins, etc. ### Unified User Directory API - **Me** — ### Unified Search API - **Search** — Search endpoint for all the apps. ## MCP-ready AI tools Truto exposes 57 tools for Gmail that AI agents can call directly. - **gmail_list_emails** — Search and list Gmail messages matching a query. Use when locating specific emails by sender, subject, label, or unread state. Pass q with Gmail search syntax (from:, to:, subject:, label:, is:unread, has:attachment, after:, before:). Results are summaries (id and threadId only); hydrate via this resource's get with format=metadata. For conversation previews with snippets, prefer threads list instead. Returns one page; pass the response's next_cursor to fetch subsequent pages. - **gmail_get_email** — Read a single Gmail message: sender, subject, date, and snippet by default via format=metadata. Use when you know the exact message to inspect. Pass format=full only when you need the body to reply or summarize — metadata is faster and usually enough. Obtain id from messages list or threads get. - **gmail_send_email** — Send a Gmail message on behalf of the authenticated user. Provide the email as plain-text RFC 2822 MIME in the raw field (headers + blank line + body); Truto base64url-encodes it before sending, so do NOT pre-encode. For attachments, build a multipart/mixed MIME and pass the whole thing as raw. Returns the sent message resource including its id and threadId. - **gmail_modify_email_labels** — Modify labels on a Gmail message (addLabelIds / removeLabelIds) without changing the body. Use when starring, marking read/unread, archiving (remove INBOX), or applying user labels. Does NOT edit subject or body — use drafts for composition. Obtain id from messages. - **gmail_trash_email** — Move a Gmail message to Trash (recoverable). Use when the user asks to delete an email and a soft delete is acceptable. Prefer this over messages delete. Obtain id from messages. - **gmail_list_conversations** — Search and list Gmail conversations (threads) with a preview snippet per thread. Use when browsing recent correspondence or getting a conversation overview. Pass q with Gmail search syntax. For pinpointing one specific email, use messages list instead. Use threads get only when you need every message in the conversation. Returns one page; pass the response's next_cursor to fetch subsequent pages. - **gmail_get_conversation** — Read a full Gmail conversation (thread) including its messages. Use when summarizing or replying in-thread and you need the complete exchange. For a single message, use messages get instead. Obtain id from threads. - **gmail_modify_conversation_labels** — Modify labels on every message in a Gmail thread. Use when archiving, starring, or labeling a whole conversation at once. Obtain id from threads. - **gmail_trash_conversation** — Move an entire Gmail conversation (thread) to Trash, including all messages. Use when the user wants to discard a whole thread. Prefer this over threads delete. Obtain id from threads. - **create_a_gmail_batch** — The batch endpoint allows you to group multiple Gmail API requests (such as sending messages, modifying labels, deleting drafts, etc.) into a single HTTP request. Each request is executed independently, and its responses are returned in a multipart response. This is especially useful for bulk operations such as modifying labels on many messages or sending multiple emails at once. - **list_all_oauth_user_info** — Retrieves basic profile information about the authenticated user in Google Calendar. The response includes essential details such as the user's unique identifier (sub), full name (name), first name (given_name), last name (family_name), profile picture URL (picture), and email address (email). - **gmail_get_attachment** — Get a specific attachment from a Gmail message by attachment id. Returns the attachment payload including its base64url-encoded data and size. Required: message_id and id. user_id defaults to "me" (the authenticated user). - **gmail_list_drafts** — List Gmail drafts with each draft id and underlying message/thread ids (no body). Use when browsing unsent mail or resolving a draft to edit or send. Results are summaries; fetch content via this resource's get method. Pass q with Gmail search syntax when filtering. Returns one page; pass the response's next_cursor to fetch subsequent pages. - **gmail_get_draft** — Read one Gmail draft including its message headers and snippet (format=metadata) or full MIME (format=full). Use when reviewing or editing an unsent message before send. Obtain id from drafts. - **create_a_gmail_draft** — Create a Gmail draft (an unsent message saved in the mailbox). Pass the email as plain-text RFC 2822 MIME in message.raw and Truto base64url-encodes it before saving. Do not pre-encode. Returns the created draft including its id. - **update_a_gmail_draft** — Update an existing Gmail draft by its id, replacing its content. Pass the email as plain-text RFC 2822 MIME in message.raw and Truto base64url-encodes it before saving. Do not pre-encode. Returns the updated draft. - **gmail_delete_draft** — Permanently delete a Gmail draft by id (not moved to Trash). Use when discarding an unsent message. This delete is permanent and cannot be undone; confirm the exact id and get explicit user confirmation before calling. Obtain id from drafts. - **send_a_gmail_draft** — Send an existing Gmail draft by its id. Obtain the id from create draft or list drafts. Returns the sent message including its id and threadId. - **list_all_gmail_history** — List the history of all changes to the mailbox for user_id after the specified startHistoryId in Gmail. Returns history records with id, messages, messagesAdded, messagesDeleted, labelsAdded, and labelsRemoved fields. - **gmail_list_labels** — List all Gmail labels (system and user-created) in one response. Use when resolving a label name to its id before filtering mail or applying labels. Gmail does not paginate this endpoint. To apply labels to mail, use messages update or threads update — not this method. - **gmail_get_label** — Read one Gmail label: name, type, and visibility settings. Use when inspecting a known label id. Obtain id from labels. - **gmail_create_label** — Create a user-defined Gmail label. Use when the user wants a new mailbox label for organizing mail. Returns the created label including its id. System labels cannot be created this way. - **gmail_delete_label** — Permanently delete a user-created Gmail label by its immutable id (e.g. Label_31 from labels). Use when removing a custom label. System labels (INBOX, STARRED, …) cannot be deleted — remove them from messages via messages update instead. This delete is permanent and cannot be undone; confirm the exact id and get explicit user confirmation before calling. Obtain id from labels. - **gmail_update_label** — Update a user-created Gmail label's name or visibility. Use when renaming a label. Obtain id from labels. System labels cannot be renamed. - **list_all_gmail_settings_sendas** — List send-as aliases for the specified user_id in Gmail. Returns the primary send-as address and any custom 'from' aliases in the sendAs array. - **get_single_gmail_settings_senda_by_id** — Get the specified send-as alias for user_id in Gmail. Returns the send-as alias details including email address and configuration. Fails with 404 if alias is not found. - **create_a_gmail_settings_senda** — Create a custom 'from' send-as alias for user_id in Gmail. Returns the created alias with fields including verification status and sanitized signature if provided. - **update_a_gmail_settings_senda_by_id** — Update a send-as alias for user_id and id in Gmail. Returns the updated send-as alias including fields like signature and email address. Note: Only service account clients with domain-wide authority can update non-primary addresses. - **delete_a_gmail_settings_senda_by_id** — Delete the specified send-as alias for user_id in Gmail. Revokes any verification required for using the alias. Returns an empty JSON object on success. - **list_all_gmail_settings_filters** — Get message filters for a Gmail user with user_id. Returns a list of filters including criteria and actions for each filter. - **get_single_gmail_settings_filter_by_id** — Get a filter by id for the user identified by user_id in Gmail. Returns the filter's id, criteria, and action fields. - **create_a_gmail_settings_filter** — Create a filter for the user identified by user_id in Gmail. Returns the created filter including its id, criteria, and action. Note: maximum of 1,000 filters can be created. - **delete_a_gmail_settings_filter_by_id** — Delete a filter by id for the user_id in Gmail. Returns an empty JSON object on success. - **list_all_gmail_settings_forwarding_addresses** — Get the list of forwarding addresses for the specified user_id in Gmail. Returns forwardingAddresses array containing addresses that may be used for forwarding. - **get_single_gmail_settings_forwarding_address_by_id** — Get the specified forwarding address for user_id in Gmail. Returns forwardingEmail and verification status fields. - **create_a_gmail_settings_forwarding_address** — Create a forwarding address for user_id in Gmail. Returns the forwarding address resource including verification status which may be 'pending' if ownership verification is required. - **delete_a_gmail_settings_forwarding_address_by_id** — Delete the specified forwarding address for user_id in Gmail. Returns an empty JSON object on success. Requires forwardingEmail as id. - **list_all_gmail_settings_delegates** — List delegates for the specified userId in Gmail. Returns delegates array with delegate details including verification status. - **get_single_gmail_settings_delegate_by_id** — Get the specified delegate for user_id in Gmail. Returns delegate's email and related delegate information. Note: delegateEmail must be the primary email address. - **create_a_gmail_settings_delegate** — Create a delegate for the user identified by user_id in Gmail. Returns the delegate's email address and verification status. The delegate must be in the same Google Workspace organization and is added with status accepted without verification email. - **delete_a_gmail_settings_delegate_by_id** — Remove the specified delegate by delegate_email for the user identified by user_id in Gmail. The delegate user must be referred to by their primary email address. Response is an empty JSON object. - **list_all_gmail_settings_cse_keypairs** — List client-side encryption key pairs for a user in Gmail. Requires user_id. Returns cseKeyPairs array with key pair details and nextPageToken for pagination. - **get_single_gmail_settings_cse_keypair_by_id** — Get an existing client-side encryption key pair by user_id and id in Gmail. Returns key pair details including encryption keys and metadata. - **create_a_gmail_settings_cse_keypair** — Create and upload a client-side encryption S/MIME public key certificate chain and private key metadata for the authenticated user in Gmail. Requires user_id. Returns the created CseKeyPair including public key certificate chain and metadata. - **list_all_gmail_settings_cse_identities** — List client-side encrypted identities for a user in Gmail. Requires user_id. Returns cseIdentities array with identity details and nextPageToken for pagination. - **get_single_gmail_settings_cse_identity_by_id** — Get client-side encryption identity configuration for user_id and id in Gmail. Returns fields of the CseIdentity resource. - **create_a_gmail_settings_cse_identity** — Create and configure a client-side encryption identity authorized to send mail from the user account in Gmail. Requires user_id. Returns the created CseIdentity with its configuration details. - **update_a_gmail_settings_cse_identity_by_id** — Update a client-side encryption identity in Gmail by associating a different key pair. Requires user_id and id (emailAddress). Returns the updated CseIdentity fields including emailAddress and key_pair_configuration. - **delete_a_gmail_settings_cse_identity_by_id** — Delete a client-side encryption identity for the authenticated user in Gmail. Requires user_id and cse_email_address. The identity cannot be restored after deletion. - **get_single_gmail_settings_auto_forwarding_by_id** — Get the auto-forwarding setting for the specified account in Gmail. Requires user_id. Returns auto-forwarding configuration including enabled status, email address, and disposition. - **update_a_gmail_settings_auto_forwarding_by_id** — Update the auto-forwarding setting for the specified user_id in Gmail. Requires a verified forwarding address when auto-forwarding is enabled. Returns the updated AutoForwarding configuration. - **get_single_gmail_settings_imap_by_id** — Get IMAP settings for the user identified by user_id in Gmail. Returns fields including enabled status, auto-expunge, and folder size limits. - **update_a_gmail_settings_imap_by_id** — Update IMAP settings for a user in Gmail. Requires userId as the user's email address or 'me'. Returns the updated ImapSettings object. - **get_single_gmail_settings_language_by_id** — Get language settings for a user in Gmail. Requires user_id. Returns language code and display name fields in the response. - **update_a_gmail_settings_language_by_id** — Update language settings for a user in Gmail using user_id. Returns the saved displayLanguage which may differ from the requested value if a close variant is used. - **get_single_gmail_settings_pop_by_id** — Get POP settings for a user in Gmail. Requires user_id. Returns fields including accessWindow, disposition, and enable status. - **update_a_gmail_settings_pop_by_id** — Update POP settings for the user identified by user_id in Gmail. Returns the updated PopSettings including access window and disposition fields. ## How it works 1. **Link your customer's Gmail account.** Use Truto's frontend SDK; we handle every OAuth and API key flow so you don't need to create the OAuth app. 2. **Authentication is automatic.** Truto refreshes tokens, stores credentials securely, and injects them into every API request. 3. **Call Truto's API to reach Gmail.** The Proxy API is a 1-to-1 mapping of the Gmail API. 4. **Get a unified response format.** Every response uses a single shape, with cursor-based pagination and data in the `result` field. ## Use cases - **Log email activity to your app's record timeline** — SaaS platforms like CRMs, ATS tools, and project management apps can sync Gmail messages and threads to automatically associate email conversations with contacts, deals, or tickets — giving users full context without leaving your product. - **Send emails through your users' Gmail accounts** — Sales engagement, outreach, and support platforms can send emails directly from end users' Gmail accounts using create_a_gmail_message, ensuring messages land in the user's Sent folder, carry their signature, and benefit from their domain's deliverability reputation. - **Generate and manage drafts programmatically** — AI copilots, support tools, and workflow automation products can push pre-composed drafts into a user's Gmail via create_a_gmail_draft, letting the user review, edit, and send from their native Gmail client — keeping them in control while reducing manual work. - **Extract attachments for automated document processing** — Expense management, contract analysis, and recruiting platforms can pull attachments from specific emails using get_single_gmail_attachment_by_id to automatically parse receipts, invoices, resumes, or contracts without any manual upload step. - **Monitor and triage inbound email with labels and filters** — Support and operations tools can programmatically apply Gmail labels to threads via update_a_gmail_thread_by_id and create server-side filters with create_a_gmail_settings_filter to route, categorize, and prioritize inbound email for end users. ## What you can build - **Bi-directional email sync with record matching** — Automatically ingest Gmail messages and threads into your app, match them to CRM contacts or support tickets by email address, and display full threaded conversation history on each record. - **Native send-as-user email composer** — Let users compose and send emails from within your app using their own Gmail account and Send As aliases, fetched via list_all_gmail_settings_sendas, so messages go out with the correct identity and signature. - **AI-powered draft generation** — Use create_a_gmail_draft to push AI-generated or template-based replies directly into a user's Gmail Drafts folder, ready for review and one-click send via gmail_drafts_send. - **Incremental email sync via History API** — Build a high-performance sync engine using list_all_gmail_history to fetch only new or changed messages since the last checkpoint, minimizing API calls and keeping your app's data fresh in near real-time. - **Automated attachment ingestion pipeline** — Scan incoming emails for attachments, download them with get_single_gmail_attachment_by_id, and feed them into OCR, parsing, or storage workflows — ideal for expense receipts, signed contracts, or candidate resumes. - **Smart inbox labeling and categorization** — Programmatically create custom labels with create_a_gmail_label and apply them to threads via update_a_gmail_thread_by_id to implement automated triage — tagging threads as 'High Priority', 'Needs Follow-up', or any custom category your product defines. ## FAQs ### How does authentication work for Gmail integrations through Truto? Truto handles the full OAuth 2.0 flow required by Google. Your end users authorize access via a consent screen, and Truto manages token storage, refresh, and revocation. You never touch raw credentials. ### How can I efficiently sync emails without polling the entire inbox? Use the list_all_gmail_history endpoint. Store the historyId from your last sync, then request only changes (new messages, label modifications, deletions) since that point. This is far more efficient than re-listing all messages. ### Does Truto support Gmail's label system, or does it map to folders? Both. The Unified Emails API exposes a Folders resource that maps to Gmail labels, giving you a normalized interface. You can also use the native Gmail label endpoints (list_all_gmail_labels, create_a_gmail_label, update_a_gmail_label_by_id) for full control over Gmail's label system, including custom labels. ### Can I send emails and manage drafts through the integration? Yes. Use create_a_gmail_message to send emails directly, or create_a_gmail_draft to stage a draft in the user's mailbox. You can update drafts with update_a_gmail_draft_by_id and send them programmatically via gmail_drafts_send. ### How do I handle bulk operations without hitting Gmail API rate limits? Truto exposes create_a_gmail_batch for batch operations, which groups multiple API calls into a single request. This significantly reduces quota consumption when performing bulk actions like labeling, archiving, or fetching multiple messages. ### What unified APIs are available alongside the native Gmail endpoints? Truto provides Unified Emails API (covering Emails, Attachments, and Folders), Unified User Directory API (for the authenticated user's profile via 'Me'), and Unified Search API. These give you a normalized schema that works across email providers, while native endpoints remain available for Gmail-specific features like filters, delegates, and Send As aliases. ## Related reading - [Connect Gmail to Claude: Organize Threads, Labels, and Aliases](https://truto.one/blog/connect-gmail-to-claude-organize-threads-labels-and-aliases/) — Learn how to connect Gmail to Claude using a managed MCP server. Discover how to automate inbox triage, manage drafts, and configure aliases via natural language. - [Connect Gmail to ChatGPT: Manage Messages, Drafts, and Settings](https://truto.one/blog/connect-gmail-to-chatgpt-manage-messages-drafts-and-settings/) — Learn how to connect Gmail to chatgpt using Truto. Step-by-step guide to tool calling, API quirks, and autonomous workflows. - [Connect Gmail to AI Agents: Automate Filters, Rules, and Messaging](https://truto.one/blog/connect-gmail-to-ai-agents-automate-filters-rules-and-messaging/) — A definitive engineering guide to connecting Gmail to AI agents. Learn how to bind Gmail tools to LLMs, handle API quirks, and automate inbox workflows.