--- 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. ### Unified User Directory API - **Me** — ### Unified Search API - **Search** — Search endpoint for all the apps. ## MCP-ready AI tools Truto exposes 58 tools for Gmail that AI agents can call directly. - **list_all_gmail_messages** — Use this endpoint to retrieve a list of messages from the user's Gmail mailbox. - **get_single_gmail_message_by_id** — Get the specified message by id for user_id in Gmail. Returns message id, threadId, labelIds, snippet, historyId, internalDate, payload, sizeEstimate, raw, and other message details. - **create_a_gmail_message** — Send a message to recipients specified in the To, Cc, and Bcc headers in Gmail. Requires user_id. Returns the sent message including id, threadId, labelIds, snippet, and internalDate. - **delete_a_gmail_message_by_id** — Delete a specific message by id for user_id in Gmail. This operation immediately and permanently deletes the message and cannot be undone. The response is an empty JSON object. - **list_all_gmail_threads** — List threads in the user's mailbox in Gmail. Requires user_id. Returns threads array with thread details, nextPageToken for pagination, and resultSizeEstimate indicating total results. - **get_single_gmail_thread_by_id** — Get the specified thread by user_id and id in Gmail. Returns thread messages with fields such as message IDs, labels, headers, and body content depending on the format parameter. - **update_a_gmail_thread_by_id** — Modify labels applied to a thread in Gmail for user_id and id. Returns the updated thread including id, snippet, historyId, and labelIds fields. - **delete_a_gmail_thread_by_id** — Delete a specific thread by id for user_id in Gmail. This operation permanently deletes the thread and all its messages and cannot be undone. - **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_gmail_userinfo** — Retrieves basic profile information about the currently authenticated user using the access token provided during OAuth 2.0 authentication. - **get_single_gmail_attachment_by_id** — Get the specified message attachment by user_id, message_id, and id in Gmail. Returns attachment data including size and base64 encoded content. - **list_all_gmail_drafts** — List drafts in the user's mailbox in Gmail. Requires user_id. Returns drafts with id and threadId. - **get_single_gmail_draft_by_id** — Get the specified draft by user_id and id in Gmail. Returns the draft's id, message, and labels. - **create_a_gmail_draft** — Create a new draft for the user identified by user_id in Gmail. Returns the created draft including its id and message details. - **update_a_gmail_draft_by_id** — Update a draft's content in Gmail using user_id and id. Returns the updated draft including its id and message details. - **delete_a_gmail_draft_by_id** — Delete a specific draft by id for the user_id in Gmail. The draft is permanently deleted and not moved to trash. The response is an empty JSON object. - **gmail_drafts_send** — Send the specified draft for user_id in Gmail. Returns the sent message including id, threadId, labelIds, snippet, and internalDate. - **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. - **list_all_gmail_labels** — List all labels in the user's mailbox in Gmail. Requires user_id. Returns label id, name, messageListVisibility, labelListVisibility, and type for each label. - **get_single_gmail_label_by_id** — Get the specified label by id for user_id in Gmail. Returns label details including id, name, message list visibility, label list visibility, type, and color. - **create_a_gmail_label** — Create a new label for the user identified by user_id in Gmail. Returns the created label including id, name, messageListVisibility, and labelListVisibility fields. - **delete_a_gmail_label_by_id** — Delete a label by id for the user_id in Gmail. This operation permanently removes the label and disassociates it from all messages and threads. - **update_a_gmail_label_by_id** — Patch the specified label for user_id and id in Gmail. Returns the updated label including its id, name, message list visibility, label list visibility, type, and color properties. - **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. - **get_single_gmail_settings_vacation_by_id** — Get vacation responder settings for a user in Gmail. Requires userId. Returns vacation responder configuration including enablement, response subject, message, and time range. - **update_a_gmail_settings_vacation_by_id** — Update vacation responder settings for a user in Gmail. Requires userId as id. Returns updated vacation settings including response subject, message, and enablement status. ## 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.