# Gmail on boxd

> Gmail is Google’s email service, featuring spam protection, search functions, and seamless integration with other G Suite apps for productivity.

- Page: https://boxd.sh/integrations/gmail/
- CLI: `run gmail` (63 commands, 23 marked common)
- SDK: `import { gmail } from "@boxd/run"`; every parameter and response type is at `@boxd/run/gmail`
- Triggers: 2
- Connect: `run auth gmail` (Sign in with Gmail), or https://app.boxd.sh/integrations/detail/gmail
- All integrations: https://boxd.sh/integrations/ (Markdown: https://boxd.sh/integrations/index.md)

## From the shell

```sh
run auth gmail      # once: prints a link to connect your account
run gmail           # list its commands
run gmail list-drafts
```

Parameters are flags (`--flag value`); object and array parameters take a JSON string. Output is YAML, or JSON with `--json`. Calls use your own connection; `--scope <name>` uses a connection shared with your team.

## From a script

```ts
import { gmail } from "@boxd/run";

const result = await gmail.listDrafts({});
console.log(result);

gmail.on("new-message", async (event) => {
  // New Gmail Message Received Trigger: runs on this machine, once per event
  console.log(event);
});
```

Run it with `run gmail.run.ts`. A script that calls `.on()` keeps running as a job and handles each event.

## Commands

Required flags are listed; `run gmail <command> --help` lists the optional ones. "common" marks what `run gmail` shows without `--all`.

| Command | SDK method | Required flags | Optional | Description |
|---|---|---|---|---|
| `add-label-to-email` | `gmail.addLabelToEmail()` | `--message-id` | 3 | 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` | `gmail.batchDeleteMessages()` | `--messageIds` | 1 | Permanently delete multiple Gmail messages in bulk, bypassing Trash with no recovery possible |
| `batch-modify-messages` ·common | `gmail.batchModifyMessages()` | `--messageIds` | 3 | Modify labels on multiple Gmail messages in one efficient API call |
| `create-email-draft` ·common | `gmail.createEmailDraft()` | — | 10 | Creates a Gmail email draft |
| `create-filter` | `gmail.createFilter()` | `--action` `--criteria` | 1 | Create a new Gmail filter with specified criteria and actions |
| `create-label` | `gmail.createLabel()` | `--label-name` | 5 | Creates a new label with a unique name in the specified user's Gmail account |
| `create-prompt-post` | `gmail.createPromptPost()` | `--message` `--organizationId` | 3 | Send a one-shot prompt to the Sanity Content Agent |
| `delete-draft` ·common | `gmail.deleteDraft()` | `--draft-id` | 1 | 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` | `gmail.deleteFilter()` | `--filter-id` | 1 | Permanently delete a Gmail filter by its ID |
| `delete-label` | `gmail.deleteLabel()` | `--label-id` | 1 | Permanently DELETES a user-created Gmail label from the account (not from a message) |
| `delete-message` ·common | `gmail.deleteMessage()` | `--message-id` | 1 | 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 to which the authenticated user has delegated access |
| `delete-thread` ·common | `gmail.deleteThread()` | `--id` | 1 | Immediately and permanently delete a specified thread and all its messages |
| `fetch-emails` ·common | `gmail.fetchEmails()` | — | 9 | Fetches a list of email messages from a Gmail account, supporting filtering, pagination, and optional full content retrieval |
| `fetch-message-by-message-id` ·common | `gmail.fetchMessageByMessageId()` | `--message-id` | 2 | 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` | `gmail.fetchMessageByThreadId()` | `--thread-id` | 2 | Retrieves messages from a Gmail thread using its `thread_id`, where the thread must be accessible by the specified `user_id` |
| `forward-message` | `gmail.forwardMessage()` | `--message-id` `--recipients` | 4 | Forward an existing Gmail message to specified recipients, preserving original body and attachments |
| `get-attachment` ·common | `gmail.getAttachment()` | `--attachment-id` `--file-name` `--message-id` | 1 | Retrieves a specific attachment by ID from a message in a user's Gmail mailbox, requiring valid message and attachment IDs |
| `get-auto-forwarding` | `gmail.getAutoForwarding()` | — | 1 | Get the auto-forwarding setting for the specified account |
| `get-contacts` | `gmail.getContacts()` | — | 4 | Fetches contacts (connections) for the authenticated Google account, allowing selection of specific data fields and pagination |
| `get-draft` ·common | `gmail.getDraft()` | `--draft-id` | 2 | Retrieves a single Gmail draft by its ID |
| `get-filter` | `gmail.getFilter()` | `--id` | 1 | Retrieve a specific Gmail filter by its ID |
| `get-label` | `gmail.getLabel()` | `--id` | 1 | Gets details for a specified Gmail label |
| `get-language-settings` | `gmail.getLanguageSettings()` | — | 1 | Retrieve the language settings for a Gmail user |
| `get-people` | `gmail.getPeople()` | — | 7 | Retrieves either a specific person's details (using `resource_name`) or lists 'Other Contacts' (if `other_contacts` is true), with `person_fields` specifying the data to return |
| `get-profile` | `gmail.getProfile()` | — | 1 | Retrieves Gmail profile information (email address, aggregate messagesTotal/threadsTotal, historyId) for a user. messagesTotal counts individual emails; threadsTotal counts conversations; neither is… |
| `get-vacation-settings` | `gmail.getVacationSettings()` | — | 1 | Retrieve vacation responder settings for a Gmail user |
| `import-message` | `gmail.importMessage()` | `--raw` | 5 | Import a message into the user's mailbox with standard email delivery scanning and classification |
| `insert-message` | `gmail.insertMessage()` | `--raw` | 3 | Insert a message into the user's mailbox similar to IMAP APPEND |
| `list-cse-identities` | `gmail.listCseIdentities()` | — | 3 | List client-side encrypted identities for an authenticated user |
| `list-cse-keypairs` | `gmail.listCseKeypairs()` | — | 3 | List client-side encryption key pairs for an authenticated user |
| `list-drafts` ·common | `gmail.listDrafts()` | — | 4 | Retrieves a paginated list of email drafts from a user's Gmail account |
| `list-filters` | `gmail.listFilters()` | — | 1 | List all Gmail filters (rules) in the mailbox |
| `list-forwarding-addresses` | `gmail.listForwardingAddresses()` | — | 1 | List all forwarding addresses for the specified Gmail account |
| `list-history` | `gmail.listHistory()` | `--start-history-id` | 5 | List Gmail mailbox change history since a known startHistoryId |
| `list-labels` | `gmail.listLabels()` | — | 2 | Retrieves all system and user-created labels for a Gmail account in a single unpaginated response |
| `list-messages` ·common ·deprecated | `gmail.listMessages()` | — | 6 | Use fetch-emails instead |
| `list-send-as` | `gmail.listSendAs()` | — | 1 | Lists the send-as aliases for a Gmail account, including the primary address and custom 'from' aliases |
| `list-smime-info` | `gmail.listSmimeInfo()` | `--send-as-email` | 1 | Lists S/MIME configs for the specified send-as alias |
| `list-threads` | `gmail.listThreads()` | — | 5 | 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` | `gmail.modifyThreadLabels()` | `--thread-id` | 3 | 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` ·common | `gmail.moveThreadToTrash()` | `--thread-id` | 1 | Moves the specified thread to the trash |
| `move-to-trash` ·common | `gmail.moveToTrash()` | `--message-id` | 1 | Moves an existing, non-deleted email message to the trash for the specified user |
| `patch-label` ·common | `gmail.patchLabel()` | `--id` `--userId` | 4 | Patches the specified user-created label |
| `patch-send-as` ·common | `gmail.patchSendAs()` | `--send-as-email` | 7 | Patch the specified send-as alias for a Gmail user |
| `remove-label` ·deprecated | `gmail.removeLabel()` | `--label-id` | 1 | Use delete-label instead |
| `reply-to-thread` ·common | `gmail.replyToThread()` | `--thread-id` | 8 | 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 instead of replying in-thread |
| `search-people` ·common | `gmail.searchPeople()` | `--query` | 3 | Searches contacts by matching the query against names, nicknames, emails, phone numbers, and organizations, optionally including 'Other Contacts' |
| `send-draft` ·common | `gmail.sendDraft()` | `--draft-id` | 1 | Sends an existing draft email AS-IS to recipients already defined within the draft |
| `send-email` ·common | `gmail.sendEmail()` | — | 10 | Sends an email via Gmail API using the authenticated user's Google profile display name |
| `settings-get-imap` | `gmail.settingsGetImap()` | — | 1 | 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` | `gmail.settingsGetPop()` | — | 1 | Retrieve POP settings for a Gmail account |
| `settings-send-as-get` | `gmail.settingsSendAsGet()` | `--send-as-email` | 1 | Retrieve a specific send-as alias configuration for a Gmail user |
| `stop-watch` | `gmail.stopWatch()` | — | 1 | Stop receiving push notifications for a Gmail mailbox |
| `untrash-message` ·common | `gmail.untrashMessage()` | `--message-id` | 1 | Remove a message from trash in Gmail |
| `untrash-thread` ·common | `gmail.untrashThread()` | `--thread-id` | 1 | Remove a thread from trash in Gmail |
| `update-draft` ·common | `gmail.updateDraft()` | `--draft-id` | 10 | Updates (replaces) an existing Gmail draft's content in-place by draft ID |
| `update-imap-settings` | `gmail.updateImapSettings()` | — | 5 | Update IMAP settings for a Gmail account |
| `update-label` ·common | `gmail.updateLabel()` | `--id` | 5 | Update the properties of an existing Gmail label |
| `update-language-settings` | `gmail.updateLanguageSettings()` | `--display-language` | 1 | Update the language settings for a Gmail user |
| `update-pop-settings` | `gmail.updatePopSettings()` | — | 3 | Update POP settings for a Gmail account |
| `update-send-as` | `gmail.updateSendAs()` | `--send-as-email` | 7 | Update a send-as alias for a Gmail user |
| `update-user-attributes-values` | `gmail.updateUserAttributesValues()` | `--attributes` `--resourceId` `--resourceType` `--userId` | 0 | Update user attribute values for a resource |
| `update-vacation-settings` | `gmail.updateVacationSettings()` | — | 9 | Update vacation responder settings for a Gmail user |

## Triggers

`gmail.on("<event>", handler)` in a script; required config goes before the handler as an object.

| Event | Name | Required config | Description |
|---|---|---|---|
| `"email-sent"` | Email Sent | — | Triggers when a Gmail message is sent by the authenticated user |
| `"new-message"` | New Gmail Message Received Trigger | — | Triggers when a new message is received in Gmail |

## Docs

- [run CLI](https://docs.boxd.sh/cli/run): Call connected integrations from the shell, connect new ones, and run automations.
- [Quickstart](https://docs.boxd.sh/guides/integrations/quickstart): Connect an integration, call it from the shell, and turn a script into an automation.
- [Connections](https://docs.boxd.sh/guides/integrations/connections): Connect an account once, for yourself or for your whole organization.
- [Scripts](https://docs.boxd.sh/guides/automations/scripts): Typed integrations, triggers, schedules and state in a .run.ts file.
- [Jobs](https://docs.boxd.sh/guides/automations/jobs): How a script becomes a background job: states, retries, sleep and wake.
- [Beyond the catalog](https://docs.boxd.sh/guides/automations/beyond-the-catalog): Reach your own APIs, databases and cloud accounts from a script.