<article class="sy-endpoint"><h3><code>GET /v1/connectors/gmail/messages</code></h3><p>Search the mailbox with a Gmail query string and return matching messages.</p><div class="sy-table-wrap"><table><thead><tr><th>Param</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>connection_id</td><td>string</td><td>yes</td><td>The authorised mailbox to search.</td></tr><tr><td>q</td><td>string</td><td>yes</td><td>A Gmail search string, for example label:support -label:synced. Runs on Google's side.</td></tr><tr><td>include_body</td><td>boolean</td><td>no</td><td>Return the message body as well as the headers. Defaults to false to keep responses small.</td></tr><tr><td>limit</td><td>integer</td><td>no</td><td>Results per page, 1 to 100. Defaults to 25.</td></tr><tr><td>cursor</td><td>string</td><td>no</td><td>Opaque cursor from the previous response.</td></tr></tbody></table></div><pre><code>{
"run_id": "run_6f38db04",
"connector": "gmail",
"status": "ok",
"data": [
{
"message_id": "18f2a9c7b1e04d55",
"thread_id": "18f2a9c7b1e04d55",
"from": "lena@harbourline.example",
"subject": "Invoice 20481 looks wrong",
"received_at": "2026-09-07T07:31:09Z",
"has_attachments": true,
"labels": ["INBOX", "support"]
}
],
"next_cursor": null
}</code></pre></article><article class="sy-endpoint"><h3><code>POST /v1/connectors/gmail/messages</code></h3><p>Send an email from the connected address, optionally inside an existing thread.</p><div class="sy-table-wrap"><table><thead><tr><th>Param</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>connection_id</td><td>string</td><td>yes</td><td>The authorised mailbox to send from.</td></tr><tr><td>to</td><td>array</td><td>yes</td><td>One or more recipient addresses. Each is validated before anything is sent.</td></tr><tr><td>subject</td><td>string</td><td>yes</td><td>The subject line. Ignored when thread_id is supplied, because a reply keeps the original.</td></tr><tr><td>body_html</td><td>string</td><td>yes</td><td>The message body. A plain text alternative is generated automatically.</td></tr><tr><td>thread_id</td><td>string</td><td>no</td><td>Reply inside this thread rather than starting a new conversation.</td></tr></tbody></table></div><pre><code>{
"run_id": "run_70491ec5",
"connector": "gmail",
"status": "ok",
"data": {
"message_id": "18f2b04e9c117a30",
"thread_id": "18f2a9c7b1e04d55",
"to": ["lena@harbourline.example"],
"sent_at": "2026-09-07T10:44:18Z"
}
}</code></pre></article><article class="sy-endpoint"><h3><code>POST /v1/connectors/gmail/messages/{message_id}/labels</code></h3><p>Apply or remove labels, the usual way to stop a message being processed twice.</p><div class="sy-table-wrap"><table><thead><tr><th>Param</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>connection_id</td><td>string</td><td>yes</td><td>The authorised mailbox holding the message.</td></tr><tr><td>add</td><td>array</td><td>no</td><td>Label names to apply. A label that does not exist is created when create_missing is true.</td></tr><tr><td>remove</td><td>array</td><td>no</td><td>Label names to strip from the message.</td></tr><tr><td>create_missing</td><td>boolean</td><td>no</td><td>Create any label in add that the mailbox does not have yet. Defaults to false.</td></tr></tbody></table></div><pre><code>{
"run_id": "run_8153fd16",
"connector": "gmail",
"status": "ok",
"data": {
"message_id": "18f2a9c7b1e04d55",
"labels": ["INBOX", "support", "synced"],
"created": ["synced"]
}
}</code></pre></article><article class="sy-endpoint"><h3><code>GET /v1/connectors/gmail/attachments/{attachment_id}</code></h3><p>Fetch an attachment, or a short lived link when the file is too large to inline.</p><div class="sy-table-wrap"><table><thead><tr><th>Param</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>connection_id</td><td>string</td><td>yes</td><td>The authorised mailbox holding the attachment.</td></tr><tr><td>message_id</td><td>string</td><td>yes</td><td>The message the attachment belongs to.</td></tr><tr><td>as</td><td>string</td><td>no</td><td>One of link or base64. Defaults to link, which is what most destination apps prefer.</td></tr></tbody></table></div><pre><code>{
"run_id": "run_92640e27",
"connector": "gmail",
"status": "ok",
"data": {
"attachment_id": "att_c41a7f",
"filename": "invoice-20481.pdf",
"mime_type": "application/pdf",
"size_bytes": 184320,
"download_url": "https://files.syncline.topclb.com/t/9f31c0aa",
"expires_at": "2026-09-07T12:44:18Z"
}
}</code></pre></article><article class="sy-endpoint"><h3><code>POST /v1/connectors/gmail/drafts</code></h3><p>Prepare a message and leave it unsent, for flows where a person reads it first.</p><div class="sy-table-wrap"><table><thead><tr><th>Param</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>connection_id</td><td>string</td><td>yes</td><td>The authorised mailbox to create the draft in.</td></tr><tr><td>to</td><td>array</td><td>yes</td><td>One or more recipient addresses.</td></tr><tr><td>subject</td><td>string</td><td>yes</td><td>The subject line for the draft.</td></tr><tr><td>body_html</td><td>string</td><td>yes</td><td>The draft body. Nothing is sent until a person clicks send in Gmail.</td></tr></tbody></table></div><pre><code>{
"run_id": "run_a3751f38",
"connector": "gmail",
"status": "ok",
"data": {
"draft_id": "r-8841002937",
"message_id": "18f2b1aa30f5c204",
"created_at": "2026-09-07T10:51:40Z"
}
}</code></pre></article>