Gmail

Developers › REST API › Forms & Integrations

REST API · 5 endpoints

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, 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).

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.

Python recipes. API client helper.

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/messagesList 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`

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/batchBatch 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

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`

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`

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`

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/sendSend

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

Field	Type		Description
`attachments`	array of `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`	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`

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 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

`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`	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`	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

`HTTPValidationError`

Field	Type		Description
`detail`	array of `ValidationError`	optional

`ValidationError`

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