# Gmail · REST API

> Read and send email through a connected Google account.

HTML version: https://developers.sheetgo.com/api/gmail/

[Developers](/index.md) › [REST API](/api.md) › [Forms & Integrations](/api.md#api-endpoints)

REST API · 5 endpoints

## Gmail

**Complete for this group.** Each operation below lists its parameters, request body, responses and errors. Every model they use is documented under [Models used on this page](#models), so you do not need another page to build a request. Base URL `https://api.sheetgo.com`; paths are complete, version included (`/rest/beta/…`): append them to the base URL exactly as shown; send `Authorization: Bearer sg_…`. Also in the API's own docs: <https://api.sheetgo.com/rest/reference/gmail> ([Markdown](https://api.sheetgo.com/rest/reference/gmail.md)).

**Conventions for every endpoint.** Lists take `page` (from 1) and `per_page` (1-100, default 50), and `total` counts **pages**, not items. Collection URLs end with `/`. `POST …/run` returns `200` when the run is *queued*; poll `GET …/run`. Google Sheets use `provider: "drive"`; column fields take letters (`"E"`). Error bodies and status codes: [REST API › Errors](/api.md#api-errors).

**Python recipes.** [API client helper](/examples.md#recipe-sheetgo-api).

Read and send email through a connected Google account.

List or search messages (Gmail search syntax), read one message in full and download its attachments, with the same envelopes and message fields as the Outlook endpoints. Reading needs Gmail read access on the user's Google connection; without it the endpoints return 412 `gmail_not_connected`. Gmail always stores sent mail in SENT, so send has no `save_to_sent_items` option.

## Operations

#### GET `/rest/beta/gmail/messages` — List Messages

List or search messages, newest first, one page at a time.

Each message is a summary (no body): ids, subject, sender, recipients, dates,
snippet, labels, read state and attachment metadata. Fetch the body with
GET /messages/{message\_id}.

##### Parameters

| Name | In | Type |  | Description |
| --- | --- | --- | --- | --- |
| `limit` | query | integer | optional | Messages per page, 1-100. Outside that range returns 400 before any call to Google is made. Default: `25` |
| `label` | query | string | optional | Gmail label to list: a system label (`INBOX`, `SENT`, `STARRED`, `UNREAD`, ...), a label id, or a user label's name (e.g. `Invoices`). Pass an empty value to list all mail. Ignored when `q` is given. Default: `"INBOX"` |
| `q` | query | string | optional | Gmail search query (the syntax of Gmail's search box), e.g. `from:ana@acme.com has:attachment newer_than:7d`. Searches all mail; narrow it inside the query (`in:inbox`, `label:invoices`). |
| `page_token` | query | string | optional | `next_page_token` from a previous response. Omit for the first page. |

##### Responses

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Successful Response | any |
| 401 | Auth failed | — |
| 422 | Validation Error | [`HTTPValidationError`](#model-HTTPValidationError) |

##### Example request

```
curl -s -X GET "https://api.sheetgo.com/rest/beta/gmail/messages" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"
```

In the API's own docs: <https://api.sheetgo.com/rest/reference/gmail#get-rest-beta-gmail-messages>

#### POST `/rest/beta/gmail/messages/batch` — Batch Messages

Fetch several messages in full in one call, in the order asked.

A missing or malformed id comes back as `{id, error: "message_not_found"}` inside
`values.messages` instead of failing the call. At most 50 ids, or 10 with
`include_attachments` (whose content may total at most 25 MB).

##### Request body (required)

`application/json` · [`GmailBatchBody`](#model-GmailBatchBody)

| Field | Type |  | Description |
| --- | --- | --- | --- |
| `ids` | array of string | required | Message ids to fetch. At most 50, or 10 when `include_attachments` is true. Min items: `1` |
| `include_attachments` | boolean | optional | Whether to return each message's attachment content (base64) as well as its metadata. Lowers the batch cap to 10; attachments may total at most 25 MB across the batch. Default: `false` |

##### Responses

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Successful Response | any |
| 401 | Auth failed | — |
| 422 | Validation Error | [`HTTPValidationError`](#model-HTTPValidationError) |

##### Example request

```
curl -s -X POST "https://api.sheetgo.com/rest/beta/gmail/messages/batch" \
  -H "Authorization: Bearer $SHEETGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
```

In the API's own docs: <https://api.sheetgo.com/rest/reference/gmail#post-rest-beta-gmail-messages-batch>

#### GET `/rest/beta/gmail/messages/{message_id}` — Get Message

Fetch one message in full: date, from, to, cc, bcc, subject, Message-ID,
labels with their names, the body (HTML when the message has one, plus the
plain-text version in `body_text`) and attachment metadata — plus attachment
content with `include_attachments=true`.

##### Parameters

| Name | In | Type |  | Description |
| --- | --- | --- | --- | --- |
| `message_id` | path | string | required | Id of the message (from a list or search). |
| `include_attachments` | query | boolean | optional | Include each attachment's content (base64). Capped at 25 MB in total — a larger message returns 413, so fetch those attachments one at a time instead. Default: `false` |

##### Responses

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Successful Response | any |
| 401 | Auth failed | — |
| 422 | Validation Error | [`HTTPValidationError`](#model-HTTPValidationError) |

##### Example request

```
curl -s -X GET "https://api.sheetgo.com/rest/beta/gmail/messages/MESSAGE_ID" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"
```

In the API's own docs: <https://api.sheetgo.com/rest/reference/gmail#get-rest-beta-gmail-messages-message-id>

#### GET `/rest/beta/gmail/messages/{message_id}/attachments/{attachment_id}` — Get Attachment

Download one attachment as its native bytes (not base64), with
`Content-Disposition: attachment; filename="..."`.

##### Parameters

| Name | In | Type |  | Description |
| --- | --- | --- | --- | --- |
| `message_id` | path | string | required | Id of the message the attachment belongs to. |
| `attachment_id` | path | string | required | Id of the attachment, from the message's `attachments` list. |

##### Responses

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Successful Response | any |
| 401 | Auth failed | — |
| 422 | Validation Error | [`HTTPValidationError`](#model-HTTPValidationError) |

##### Example request

```
curl -s -X GET "https://api.sheetgo.com/rest/beta/gmail/messages/MESSAGE_ID/attachments/ATTACHMENT_ID" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"
```

In the API's own docs: <https://api.sheetgo.com/rest/reference/gmail#get-rest-beta-gmail-messages-message-id-attachments-attachment-id>

#### POST `/rest/beta/gmail/send` — Send

Send a message through the connected Google account.

Gmail always stores the sent message in SENT — there is no
`save_to_sent_items` equivalent. Total attachment bytes are capped at 3 MB
and recipients at 50, matching the Outlook contract.

##### Request body (required)

`application/json` · [`GmailSendBody`](#model-GmailSendBody)

| Field | Type |  | Description |
| --- | --- | --- | --- |
| `attachments` | array of [`AttachmentIn`](#model-AttachmentIn) | optional | Files to attach: at most 10, totalling no more than 3 MB once decoded. Default: `[]` |
| `bcc` | array of string | optional | Blind-carbon-copy recipients, hidden from other recipients. Default: `[]` |
| `body` | [`BodyContent`](#model-BodyContent) | required | The message body and whether it is plain text or HTML. |
| `cc` | array of string | optional | Carbon-copy recipients, visible to everyone. Default: `[]` |
| `subject` | string | optional | Subject line. Optional; defaults to an empty subject. Default: `""` |
| `to` | array of string | required | Primary recipients. At least one is required; `to`, `cc` and `bcc` together may not exceed 50 addresses. Min items: `1` |

##### Responses

| Status | Meaning | Body |
| --- | --- | --- |
| 202 | Successful Response | any |
| 401 | Auth failed | — |
| 422 | Validation Error | [`HTTPValidationError`](#model-HTTPValidationError) |

##### Example request

```
curl -s -X POST "https://api.sheetgo.com/rest/beta/gmail/send" \
  -H "Authorization: Bearer $SHEETGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d @body.json
```

In the API's own docs: <https://api.sheetgo.com/rest/reference/gmail#post-rest-beta-gmail-send>

## Models used on this page

Every request and response model referenced above, including nested ones (6). The full catalogue is on the [Models](/api/models.md) page.

#### `AttachmentIn`

| Field | Type |  | Description |
| --- | --- | --- | --- |
| `content_base64` | string | required | The file's bytes, base64-encoded. All attachments on one message must total no more than 3 MB decoded. |
| `content_type` | string | required | MIME type of the attachment, e.g. `application/pdf`. |
| `filename` | string | required | File name the recipient will see, including the extension. |

#### `BodyContent`

| Field | Type |  | Description |
| --- | --- | --- | --- |
| `content` | string | required | The message body itself, in the format named by `content_type`. |
| `content_type` | one of `"text"`, `"html"` | optional | How `content` should be interpreted: `text` for plain text, `html` for an HTML body. Default: `"text"` |

#### `GmailBatchBody`

Fetch several messages in one request, by id (SG-14893; mirrors Outlook's).

| Field | Type |  | Description |
| --- | --- | --- | --- |
| `ids` | array of string | required | Message ids to fetch. At most 50, or 10 when `include_attachments` is true. Min items: `1` |
| `include_attachments` | boolean | optional | Whether to return each message's attachment content (base64) as well as its metadata. Lowers the batch cap to 10; attachments may total at most 25 MB across the batch. Default: `false` |

Used by: [POST /rest/beta/gmail/messages/batch](/api/gmail.md#post-rest-beta-gmail-messages-batch)

#### `GmailSendBody`

One message to send through the authorized Gmail account.

Gmail always stores a sent message in SENT, so there is no equivalent of
Outlook's `save_to_sent_items`.

| Field | Type |  | Description |
| --- | --- | --- | --- |
| `attachments` | array of [`AttachmentIn`](#model-AttachmentIn) | optional | Files to attach: at most 10, totalling no more than 3 MB once decoded. Default: `[]` |
| `bcc` | array of string | optional | Blind-carbon-copy recipients, hidden from other recipients. Default: `[]` |
| `body` | [`BodyContent`](#model-BodyContent) | required | The message body and whether it is plain text or HTML. |
| `cc` | array of string | optional | Carbon-copy recipients, visible to everyone. Default: `[]` |
| `subject` | string | optional | Subject line. Optional; defaults to an empty subject. Default: `""` |
| `to` | array of string | required | Primary recipients. At least one is required; `to`, `cc` and `bcc` together may not exceed 50 addresses. Min items: `1` |

Used by: [POST /rest/beta/gmail/send](/api/gmail.md#post-rest-beta-gmail-send)

#### `HTTPValidationError`

| Field | Type |  | Description |
| --- | --- | --- | --- |
| `detail` | array of [`ValidationError`](#model-ValidationError) | optional |  |

Used by: [GET /rest/beta/workflows/](/api/workflows.md#get-rest-beta-workflows), [POST /rest/beta/workflows/](/api/workflows.md#post-rest-beta-workflows), [POST /rest/beta/workflows/run/{id}](/api/workflows.md#post-rest-beta-workflows-run-id), [GET /rest/beta/workflows/{id}](/api/workflows.md#get-rest-beta-workflows-id), [PATCH /rest/beta/workflows/{id}](/api/workflows.md#patch-rest-beta-workflows-id), [DELETE /rest/beta/workflows/{id}](/api/workflows.md#delete-rest-beta-workflows-id), [GET /rest/beta/workflows/{id}/collaborators](/api/workflows.md#get-rest-beta-workflows-id-collaborators), [POST /rest/beta/workflows/{id}/collaborators](/api/workflows.md#post-rest-beta-workflows-id-collaborators), [DELETE /rest/beta/workflows/{id}/collaborators](/api/workflows.md#delete-rest-beta-workflows-id-collaborators), [PATCH /rest/beta/workflows/{id}/collaborators/{email}](/api/workflows.md#patch-rest-beta-workflows-id-collaborators-email), [DELETE /rest/beta/workflows/{id}/collaborators/{email}](/api/workflows.md#delete-rest-beta-workflows-id-collaborators-email), [GET /rest/beta/workflows/{id}/destinations](/api/workflows.md#get-rest-beta-workflows-id-destinations), [GET /rest/beta/workflows/{id}/files](/api/workflows.md#get-rest-beta-workflows-id-files), [GET /rest/beta/workflows/{id}/general-access](/api/workflows.md#get-rest-beta-workflows-id-general-access), [PUT /rest/beta/workflows/{id}/general-access](/api/workflows.md#put-rest-beta-workflows-id-general-access), [DELETE /rest/beta/workflows/{id}/general-access](/api/workflows.md#delete-rest-beta-workflows-id-general-access), [POST /rest/beta/workflows/{id}/leave](/api/workflows.md#post-rest-beta-workflows-id-leave), [POST /rest/beta/workflows/{id}/request-access](/api/workflows.md#post-rest-beta-workflows-id-request-access), [GET /rest/beta/workflows/{id}/run](/api/workflows.md#get-rest-beta-workflows-id-run), [POST /rest/beta/workflows/{id}/run](/api/workflows.md#post-rest-beta-workflows-id-run), [GET /rest/beta/workflows/{id}/sources](/api/workflows.md#get-rest-beta-workflows-id-sources), [GET /rest/beta/automations/](/api/automations.md#get-rest-beta-automations), [POST /rest/beta/automations/run/{id}](/api/automations.md#post-rest-beta-automations-run-id), [GET /rest/beta/automations/{id}](/api/automations.md#get-rest-beta-automations-id), [DELETE /rest/beta/automations/{id}](/api/automations.md#delete-rest-beta-automations-id), [GET /rest/beta/automations/{id}/destinations](/api/automations.md#get-rest-beta-automations-id-destinations), [GET /rest/beta/automations/{id}/files](/api/automations.md#get-rest-beta-automations-id-files), [GET /rest/beta/automations/{id}/run](/api/automations.md#get-rest-beta-automations-id-run), [POST /rest/beta/automations/{id}/run](/api/automations.md#post-rest-beta-automations-id-run), [GET /rest/beta/automations/{id}/sources](/api/automations.md#get-rest-beta-automations-id-sources), [GET /rest/beta/workflows/{id}/trigger](/api/triggers.md#get-rest-beta-workflows-id-trigger), [DELETE /rest/beta/workflows/{id}/trigger](/api/triggers.md#delete-rest-beta-workflows-id-trigger), [GET /rest/beta/workflows/{id}/dashboard](/api/dashboards.md#get-rest-beta-workflows-id-dashboard), [DELETE /rest/beta/workflows/{id}/dashboard/elements/{element\_id}](/api/dashboards.md#delete-rest-beta-workflows-id-dashboard-elements-element-id), [GET /rest/beta/workflows/{id}/dashboard/elements/{element\_id}/data](/api/dashboards.md#get-rest-beta-workflows-id-dashboard-elements-element-id-data), [PUT /rest/beta/workflows/{id}/dashboard/publish](/api/dashboards.md#put-rest-beta-workflows-id-dashboard-publish), [GET /rest/beta/workflows/{workflow\_id}/forms/](/api/forms.md#get-rest-beta-workflows-workflow-id-forms), [POST /rest/beta/workflows/{workflow\_id}/forms/](/api/forms.md#post-rest-beta-workflows-workflow-id-forms), [GET /rest/beta/workflows/{workflow\_id}/forms/{form\_id}](/api/forms.md#get-rest-beta-workflows-workflow-id-forms-form-id), [PATCH /rest/beta/workflows/{workflow\_id}/forms/{form\_id}](/api/forms.md#patch-rest-beta-workflows-workflow-id-forms-form-id), [DELETE /rest/beta/workflows/{workflow\_id}/forms/{form\_id}](/api/forms.md#delete-rest-beta-workflows-workflow-id-forms-form-id), [GET /rest/beta/workflows/{workflow\_id}/forms/{form\_id}/responses](/api/forms.md#get-rest-beta-workflows-workflow-id-forms-form-id-responses), [HEAD /rest/beta/workflows/{workflow\_id}/forms/{form\_id}/responses](/api/forms.md#head-rest-beta-workflows-workflow-id-forms-form-id-responses), [GET /rest/beta/automations/{automation\_id}/webhook](/api/webhook.md#get-rest-beta-automations-automation-id-webhook), [GET /rest/beta/workflows/{workflow\_id}/webhooks](/api/webhook.md#get-rest-beta-workflows-workflow-id-webhooks), [GET /rest/beta/api-destination/{public\_id}](/api/api-destination.md#get-rest-beta-api-destination-public-id), [HEAD /rest/beta/api-destination/{public\_id}](/api/api-destination.md#head-rest-beta-api-destination-public-id), [GET /rest/beta/integrations/{provider}/options](/api/integrations.md#get-rest-beta-integrations-provider-options), [GET /rest/beta/outlook/messages](/api/outlook.md#get-rest-beta-outlook-messages), [POST /rest/beta/outlook/messages/batch](/api/outlook.md#post-rest-beta-outlook-messages-batch), [GET /rest/beta/outlook/messages/{message\_id}](/api/outlook.md#get-rest-beta-outlook-messages-message-id), [GET /rest/beta/outlook/messages/{message\_id}/attachments/{attachment\_id}](/api/outlook.md#get-rest-beta-outlook-messages-message-id-attachments-attachment-id), [POST /rest/beta/outlook/send](/api/outlook.md#post-rest-beta-outlook-send), [GET /rest/beta/gmail/messages](/api/gmail.md#get-rest-beta-gmail-messages), [POST /rest/beta/gmail/messages/batch](/api/gmail.md#post-rest-beta-gmail-messages-batch), [GET /rest/beta/gmail/messages/{message\_id}](/api/gmail.md#get-rest-beta-gmail-messages-message-id), [GET /rest/beta/gmail/messages/{message\_id}/attachments/{attachment\_id}](/api/gmail.md#get-rest-beta-gmail-messages-message-id-attachments-attachment-id), [POST /rest/beta/gmail/send](/api/gmail.md#post-rest-beta-gmail-send), [GET /rest/beta/files/{provider}](/api/files.md#get-rest-beta-files-provider), [GET /rest/beta/files/{provider}/roots](/api/files.md#get-rest-beta-files-provider-roots), [GET /rest/beta/files/{provider}/search](/api/files.md#get-rest-beta-files-provider-search), [GET /rest/beta/files/{provider}/{file\_id}](/api/files.md#get-rest-beta-files-provider-file-id), [GET /rest/beta/bigquery/projects](/api/bigquery.md#get-rest-beta-bigquery-projects), [GET /rest/beta/bigquery/projects/{project}/datasets](/api/bigquery.md#get-rest-beta-bigquery-projects-project-datasets), [GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables](/api/bigquery.md#get-rest-beta-bigquery-projects-project-datasets-dataset-tables), [GET /rest/beta/bigquery/projects/{project}/datasets/{dataset}/tables/{table}](/api/bigquery.md#get-rest-beta-bigquery-projects-project-datasets-dataset-tables-table), [POST /rest/beta/bigquery/projects/{project}/validate-query](/api/bigquery.md#post-rest-beta-bigquery-projects-project-validate-query), [POST /rest/auth/refresh](/api/auth.md#post-rest-auth-refresh), [POST /rest/auth/token](/api/auth.md#post-rest-auth-token)

#### `ValidationError`

| Field | Type |  | Description |
| --- | --- | --- | --- |
| `loc` | array of string or integer | required |  |
| `msg` | string | required |  |
| `type` | string | required |  |