# gmail

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.

Base URL: `https://api.sheetgo.com`. Paths are complete, version included (`/rest/beta/...`): append them to the base URL exactly as shown. Start page: https://api.sheetgo.com/rest/reference.md

This page documents every endpoint of the group. Request and response shapes link to model pages; fetch the model pages an endpoint links before building a body.

Guide: [Rate Limiting](https://api.sheetgo.com/rest/guides/rate-limiting.md)

Every endpoint is rate limited; see the guide [Rate Limiting](https://api.sheetgo.com/rest/guides/rate-limiting.md).

<a id="post-rest-beta-gmail-messages-batch"></a>
## 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).

Authentication, any one of: `default`; `Developer Access`; `sheetgo-api-key`.

**Request body**

Content type `application/json`. Required.

Body: [GmailBatchBody](https://api.sheetgo.com/rest/reference/models/GmailBatchBody.md)

**Responses**

- `200` Successful Response
- `401` Auth failed
- `422` Validation Error. Schema: [HTTPValidationError](https://api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [GmailBatchBody](https://api.sheetgo.com/rest/reference/models/GmailBatchBody.md), [HTTPValidationError](https://api.sheetgo.com/rest/reference/models/HTTPValidationError.md).

<a id="get-rest-beta-gmail-messages"></a>
## 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}.

Authentication, any one of: `default`; `Developer Access`; `sheetgo-api-key`.

**Parameters**

| Name | In | Type | Required | Description | Allowed values / default / constraints |
| --- | --- | --- | --- | --- | --- |
| `limit` | query | integer | no | Messages per page, 1-100. Outside that range returns 400 before any call to Google is made. | default: `25` |
| `label` | query | string, nullable | no | 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, nullable | no | 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, nullable | no | `next_page_token` from a previous response. Omit for the first page. |  |

**Responses**

- `200` Successful Response
- `401` Auth failed
- `422` Validation Error. Schema: [HTTPValidationError](https://api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [HTTPValidationError](https://api.sheetgo.com/rest/reference/models/HTTPValidationError.md).

<a id="get-rest-beta-gmail-messages-message-id"></a>
## 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`.

Authentication, any one of: `default`; `Developer Access`; `sheetgo-api-key`.

**Parameters**

| Name | In | Type | Required | Description | Allowed values / default / constraints |
| --- | --- | --- | --- | --- | --- |
| `message_id` | path | string | yes | Id of the message (from a list or search). |  |
| `include_attachments` | query | boolean | no | 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**

- `200` Successful Response
- `401` Auth failed
- `422` Validation Error. Schema: [HTTPValidationError](https://api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [HTTPValidationError](https://api.sheetgo.com/rest/reference/models/HTTPValidationError.md).

<a id="get-rest-beta-gmail-messages-message-id-attachments-attachment-id"></a>
## 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="..."`.

Authentication, any one of: `default`; `Developer Access`; `sheetgo-api-key`.

**Parameters**

| Name | In | Type | Required | Description | Allowed values / default / constraints |
| --- | --- | --- | --- | --- | --- |
| `message_id` | path | string | yes | Id of the message the attachment belongs to. |  |
| `attachment_id` | path | string | yes | Id of the attachment, from the message's `attachments` list. |  |

**Responses**

- `200` Successful Response
- `401` Auth failed
- `422` Validation Error. Schema: [HTTPValidationError](https://api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [HTTPValidationError](https://api.sheetgo.com/rest/reference/models/HTTPValidationError.md).

<a id="post-rest-beta-gmail-send"></a>
## 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.

Authentication, any one of: `default`; `Developer Access`; `sheetgo-api-key`.

**Request body**

Content type `application/json`. Required.

Body: [GmailSendBody](https://api.sheetgo.com/rest/reference/models/GmailSendBody.md)

**Responses**

- `202` Successful Response
- `401` Auth failed
- `422` Validation Error. Schema: [HTTPValidationError](https://api.sheetgo.com/rest/reference/models/HTTPValidationError.md)

Read next: [GmailSendBody](https://api.sheetgo.com/rest/reference/models/GmailSendBody.md), [HTTPValidationError](https://api.sheetgo.com/rest/reference/models/HTTPValidationError.md).

---

More: start page https://api.sheetgo.com/rest/reference.md, everything in one file https://api.sheetgo.com/rest/llms-full.txt, OpenAPI https://api.sheetgo.com/rest/openapi.json.