> ## Documentation Index > Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt > Use this file to discover all available pages before exploring further. # Gmail > Gmail is Google’s email service, featuring spam protection, search functions, and seamless integration with other G Suite apps for productivity Gmail is Google’s email service, featuring spam protection, search functions, and seamless integration with other G Suite apps for productivity `gmail` · **63 tools** · **2 triggers** ## Connect it ```bash theme={"theme":"github-dark"} run auth gmail run auth gmail --scope team # shared with the organization ``` Or from the [Integrations page](https://app.boxd.sh/integrations) in the console. See [Connections](/guides/integrations/connections) for personal versus shared, and who may remove one. ## Use it ```bash theme={"theme":"github-dark"} run gmail # common commands run gmail --all # every command ``` ```ts theme={"theme":"github-dark"} import { gmail } from "@boxd/run"; ``` ## Common tools | Tool | What it does | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `batch-modify-messages` | Modify labels on multiple Gmail messages in one efficient API call. | | `create-email-draft` | Creates a Gmail email draft. While all fields are optional per the Gmail API, practical validation requires at least one of recipient\_email, cc, or... | | `delete-draft` | Permanently deletes a specific Gmail draft using its ID with no recovery possible; verify the correct `draft_id` and obtain explicit user confirmation before calling. | | `delete-message` | Permanently deletes a specific email message by its ID from a Gmail mailbox; for `user_id`, use 'me' for the authenticated user or an email address... | | `delete-thread` | Tool to immediately and permanently delete a specified thread and all its messages. | | `fetch-emails` | Fetches a list of email messages from a Gmail account, supporting filtering, pagination, and optional full content retrieval. | | `fetch-message-by-message-id` | Fetches a specific email message by its ID, provided the `message_id` exists and is accessible to the authenticated `user_id`. | | `get-attachment` | Retrieves a specific attachment by ID from a message in a user's Gmail mailbox, requiring valid message and attachment IDs. | | `get-draft` | Retrieves a single Gmail draft by its ID. Use this to fetch and inspect draft content before sending via GMAIL\_SEND\_DRAFT. | | `list-drafts` | Retrieves a paginated list of email drafts from a user's Gmail account. | | `list-messages` | DEPRECATED: Use GMAIL\_FETCH\_EMAILS instead. Lists the messages in the user's mailbox. | | `move-thread-to-trash` | Moves the specified thread to the trash. Any messages that belong to the thread are also moved to the trash. | | `move-to-trash` | Moves an existing, non-deleted email message to the trash for the specified user. | | `patch-label` | Patches the specified user-created label. System labels (e.g., INBOX, SENT, SPAM) cannot be modified and will be rejected. | | `patch-send-as` | Tool to patch the specified send-as alias for a Gmail user. Use when you need to update properties of an existing send-as email address such as... | | `reply-to-thread` | Sends a reply within a specific Gmail thread using the original thread's subject; do not provide a custom subject as it will start a new conversation... | | `search-people` | Searches contacts by matching the query against names, nicknames, emails, phone numbers, and organizations, optionally including 'Other Contacts'. | | `send-draft` | Sends an existing draft email AS-IS to recipients already defined within the draft. | | `send-email` | Sends an email via Gmail API using the authenticated user's Google profile display name. | | `untrash-message` | Tool to remove a message from trash in Gmail. Use when you need to restore a previously trashed email message. | | `untrash-thread` | Tool to remove a thread from trash in Gmail. Use when you need to restore a deleted thread and its messages. | | `update-draft` | Updates (replaces) an existing Gmail draft's content in-place by draft ID. | | `update-label` | Tool to update the properties of an existing Gmail label. Use when you need to modify label name, visibility settings, or color. | | Tool | What it does | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `add-label-to-email` | Adds and/or removes specified Gmail labels for a message; ensure `message_id` and all `label_ids` are valid (use 'listLabels' for custom label IDs). | | `batch-delete-messages` | Tool to permanently delete multiple Gmail messages in bulk, bypassing Trash with no recovery possible. | | `batch-modify-messages` | Modify labels on multiple Gmail messages in one efficient API call. | | `create-email-draft` | Creates a Gmail email draft. While all fields are optional per the Gmail API, practical validation requires at least one of recipient\_email, cc, or... | | `create-filter` | Tool to create a new Gmail filter with specified criteria and actions. | | `create-label` | Creates a new label with a unique name in the specified user's Gmail account. | | `create-prompt-post` | Send a one-shot prompt to the Sanity Content Agent. Stateless one-shot prompt endpoint. | | `delete-draft` | Permanently deletes a specific Gmail draft using its ID with no recovery possible; verify the correct `draft_id` and obtain explicit user confirmation before calling. | | `delete-filter` | Tool to permanently delete a Gmail filter by its ID. Use when you need to remove an existing email filtering rule. | | `delete-label` | Permanently DELETES a user-created Gmail label from the account (not from a message). | | `delete-message` | Permanently deletes a specific email message by its ID from a Gmail mailbox; for `user_id`, use 'me' for the authenticated user or an email address... | | `delete-thread` | Tool to immediately and permanently delete a specified thread and all its messages. | | `fetch-emails` | Fetches a list of email messages from a Gmail account, supporting filtering, pagination, and optional full content retrieval. | | `fetch-message-by-message-id` | Fetches a specific email message by its ID, provided the `message_id` exists and is accessible to the authenticated `user_id`. | | `fetch-message-by-thread-id` | Retrieves messages from a Gmail thread using its `thread_id`, where the thread must be accessible by the specified `user_id`. | | `forward-message` | Forward an existing Gmail message to specified recipients, preserving original body and attachments. | | `get-attachment` | Retrieves a specific attachment by ID from a message in a user's Gmail mailbox, requiring valid message and attachment IDs. | | `get-auto-forwarding` | Tool to get the auto-forwarding setting for the specified account. | | `get-contacts` | Fetches contacts (connections) for the authenticated Google account, allowing selection of specific data fields and pagination. | | `get-draft` | Retrieves a single Gmail draft by its ID. Use this to fetch and inspect draft content before sending via GMAIL\_SEND\_DRAFT. | | `get-filter` | Tool to retrieve a specific Gmail filter by its ID. Use when you need to inspect the criteria and actions of an existing filter. | | `get-label` | Gets details for a specified Gmail label. Use this to retrieve label information including name, type, visibility settings, message/thread counts, and color. | | `get-language-settings` | Tool to retrieve the language settings for a Gmail user. Use when you need to determine the display language preference for the authenticated user or... | | `get-people` | Retrieves either a specific person's details (using `resource_name`) or lists 'Other Contacts' (if `other_contacts` is true), with `person_fields`... | | `get-profile` | Retrieves Gmail profile information (email address, aggregate messagesTotal/threadsTotal, historyId) for a user. messagesTotal counts individual... | | `get-vacation-settings` | Tool to retrieve vacation responder settings for a Gmail user. | | `import-message` | Tool to import a message into the user's mailbox with standard email delivery scanning and classification. | | `insert-message` | Tool to insert a message into the user's mailbox similar to IMAP APPEND. | | `list-cse-identities` | Tool to list client-side encrypted identities for an authenticated user. | | `list-cse-keypairs` | Tool to list client-side encryption key pairs for an authenticated user. | | `list-drafts` | Retrieves a paginated list of email drafts from a user's Gmail account. | | `list-filters` | Tool to list all Gmail filters (rules) in the mailbox. Use for security audits to detect malicious filter rules or before creating new filters to avoid duplicates. | | `list-forwarding-addresses` | Tool to list all forwarding addresses for the specified Gmail account. | | `list-history` | Tool to list Gmail mailbox change history since a known startHistoryId. | | `list-labels` | Retrieves all system and user-created labels for a Gmail account in a single unpaginated response. | | `list-messages` | DEPRECATED: Use GMAIL\_FETCH\_EMAILS instead. Lists the messages in the user's mailbox. | | `list-send-as` | Lists the send-as aliases for a Gmail account, including the primary address and custom 'from' aliases. | | `list-smime-info` | Lists S/MIME configs for the specified send-as alias. Use when you need to retrieve all S/MIME certificate configurations associated with a specific... | | `list-threads` | Retrieves a list of email threads from a Gmail account, identified by `user_id` (email address or 'me'), supporting filtering and pagination. | | `modify-thread-labels` | Adds or removes specified existing label IDs from a Gmail thread, affecting all its messages; ensure the thread ID is valid. | | `move-thread-to-trash` | Moves the specified thread to the trash. Any messages that belong to the thread are also moved to the trash. | | `move-to-trash` | Moves an existing, non-deleted email message to the trash for the specified user. | | `patch-label` | Patches the specified user-created label. System labels (e.g., INBOX, SENT, SPAM) cannot be modified and will be rejected. | | `patch-send-as` | Tool to patch the specified send-as alias for a Gmail user. Use when you need to update properties of an existing send-as email address such as... | | `remove-label` | DEPRECATED: Use GMAIL\_DELETE\_LABEL instead. Permanently deletes a specific, existing user-created Gmail label by its ID for a user; cannot delete system labels. | | `reply-to-thread` | Sends a reply within a specific Gmail thread using the original thread's subject; do not provide a custom subject as it will start a new conversation... | | `search-people` | Searches contacts by matching the query against names, nicknames, emails, phone numbers, and organizations, optionally including 'Other Contacts'. | | `send-draft` | Sends an existing draft email AS-IS to recipients already defined within the draft. | | `send-email` | Sends an email via Gmail API using the authenticated user's Google profile display name. | | `settings-get-imap` | Retrieves the IMAP settings for a Gmail user account, including whether IMAP is enabled, auto-expunge behavior, expunge behavior, and maximum folder size. | | `settings-get-pop` | Tool to retrieve POP settings for a Gmail account. Use when you need to check the current POP configuration including access window and message disposition. | | `settings-send-as-get` | Tool to retrieve a specific send-as alias configuration for a Gmail user. | | `stop-watch` | Tool to stop receiving push notifications for a Gmail mailbox. | | `untrash-message` | Tool to remove a message from trash in Gmail. Use when you need to restore a previously trashed email message. | | `untrash-thread` | Tool to remove a thread from trash in Gmail. Use when you need to restore a deleted thread and its messages. | | `update-draft` | Updates (replaces) an existing Gmail draft's content in-place by draft ID. | | `update-imap-settings` | Tool to update IMAP settings for a Gmail account. Use when you need to modify IMAP configuration such as enabling/disabling IMAP, setting... | | `update-label` | Tool to update the properties of an existing Gmail label. Use when you need to modify label name, visibility settings, or color. | | `update-language-settings` | Tool to update the language settings for a Gmail user. Use when you need to change the display language preference for the authenticated user or a specific Gmail account. | | `update-pop-settings` | Tool to update POP settings for a Gmail account. Use when you need to configure POP access window or message disposition behavior. | | `update-send-as` | Tool to update a send-as alias for a Gmail user. Use when you need to modify display name, signature, reply-to address, or SMTP settings for a send-as email address. | | `update-user-attributes-values` | Update user attribute values for a resource. Use this action to set or update custom attributes for a user within an organization or project. | | `update-vacation-settings` | Tool to update vacation responder settings for a Gmail user. | ## Triggers (2) Subscribe with `.on(...)` in a script. A trigger with required configuration takes it as the second argument. | Trigger | Needs | What fires it | | ---------------------------------- | ------- | ----------------------------------------------------------------------------- | | Email Sent | nothing | Triggers when a Gmail message is sent by the authenticated user. It polls the | | New Gmail Message Received Trigger | nothing | Triggers when a new message is received in Gmail. | [Open Gmail in the console →](https://app.boxd.sh/integrations/detail/gmail)