# Outlook email · REST API

> Integration endpoints used by the Sheetgo add-in for Microsoft Outlook to connect mailbox data to workflows.

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

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

REST API · 5 endpoints

## Outlook email

**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/outlook> ([Markdown](https://api.sheetgo.com/rest/reference/outlook.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).

Integration endpoints used by the Sheetgo add-in for Microsoft Outlook to connect mailbox data to workflows.

## Operations

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

Page through messages in a folder.

`folder` is a snake-case name (e.g. "inbox") mapped to a well-known mail
folder; unknown values return 400. `limit` is bounded to [1, 100]; a value
outside the range returns 400 before any upstream call is made.

##### Parameters

| Name | In | Type |  | Description |
| --- | --- | --- | --- | --- |
| `folder` | query | string | optional | Well-known mail folder to read, snake\_case (for example `inbox`, `sent_items`, `drafts`). An unknown name returns 400. Default: `"inbox"` |
| `limit` | query | integer | optional | Messages per page, 1-100. Outside that range returns 400 before any call to Microsoft is made. Default: `25` |
| `page_token` | query | string | optional | Opaque token from a previous response's paging cursor. 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/outlook/messages" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"
```

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

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

Resolve a list of message ids to message bodies in one shot.

Missing or cross-owner ids come back as `{id, error: "message_not_found"}`
entries inside `values.messages` rather than failing the whole call.

##### Request body (required)

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

| 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 as well as its metadata. Lowers the batch cap to 10. 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/outlook/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/outlook#post-rest-beta-outlook-messages-batch>

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

Fetch one message by id.

`include_attachments=true` opts the response into the
`$expand=attachments` Graph path; the controller enforces the 25 MB
total cap and raises 413 `AttachmentsTooLarge` if exceeded. For larger
attachments, fall back to the per-attachment binary endpoint below.

##### Parameters

| Name | In | Type |  | Description |
| --- | --- | --- | --- | --- |
| `message_id` | path | string | required | Id of the message to fetch. |
| `include_attachments` | query | boolean | optional | Include each attachment's content in the response. 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/outlook/messages/MESSAGE_ID" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"
```

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

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

Stream a single attachment as its native bytes (NOT base64-wrapped).

Returns `application/<original mime>` with a
`Content-Disposition: attachment; filename="..."` header. Filenames are
escaped for the `"` delimiter — a malicious upload couldn't smuggle
extra header fields via a crafted name.

##### 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 to download. |

##### 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/outlook/messages/MESSAGE_ID/attachments/ATTACHMENT_ID" \
  -H "Authorization: Bearer $SHEETGO_API_KEY"
```

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

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

Send a message through the connected Microsoft account.

Body validation (recipient count, attachment count, attachment total size)
runs before this handler; invalid input returns 422 with the field-level
reason. An address rejected upstream returns 400.

Defaults: `save_to_sent_items=True`.

##### Request body (required)

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

| 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: `[]` |
| `save_to_sent_items` | boolean | optional | Whether to keep a copy in the account's Sent Items folder. Set false to send without recording it. Default: `true` |
| `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/outlook/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/outlook#post-rest-beta-outlook-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. |

#### `BatchBody`

Fetch several messages in one request, by id.

| 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 as well as its metadata. Lowers the batch cap to 10. Default: `false` |

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

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

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

#### `SendBody`

One message to send through the authorized Outlook account.

| 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: `[]` |
| `save_to_sent_items` | boolean | optional | Whether to keep a copy in the account's Sent Items folder. Set false to send without recording it. Default: `true` |
| `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/outlook/send](/api/outlook.md#post-rest-beta-outlook-send)

#### `ValidationError`

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