# SourceGmail-Input

Read emails from the user's Gmail and save their attachments, bodies or
fields into a folder — or, with `extract=fields_table`, their fields as rows
of a spreadsheet (SG-14893).

Must be the only source, with no processors and exactly one destination: a
`folder`, or a `file` for `fields_table` — see validate_gmail_automation.
Gmail is only ever read.

Type: object

Fields typed as another model are documented on that model's page; fetch it before filling the field.

| Field | Type | Required | Description | Allowed values / default / constraints |
| --- | --- | --- | --- | --- |
| `type` | string | yes | Marks this source as **Gmail**: emails from the user's mailbox. | const: `"gmail"` |
| `mailbox` | [GmailMailbox](https://api.sheetgo.com/rest/reference/models/GmailMailbox.md) | no | `inbox`, `sent` or `anywhere` (all mail, including spam and trash). The Google account must be connected in Sheetgo with permission to read mail (412 `gmail_not_connected` otherwise). | default: `"inbox"` |
| `extract` | [GmailExtract](https://api.sheetgo.com/rest/reference/models/GmailExtract.md) | no | `attachments` saves each email's file attachments into a folder; `body` saves each email's body as `<subject>.html`; `fields` saves that body with the message's date, from, to, cc, bcc, subject, attachment names, Message-ID and labels above it. `fields_table` writes those same fields to a SPREADSHEET instead — one row per email, with the body as plain text and as HTML, the columns chosen with `columns` — and so needs a `file` destination (gsheets, xlsx or csv) rather than a `folder`. That destination always appends: each run adds the emails that arrived since the previous one, and a large mailbox is copied over several runs. Cells are written as plain values, so a subject or body starting with `=` is never run as a formula. | default: `"attachments"` |
| `process_once` | boolean | no | Skip emails already saved by an earlier run. Always on for `fields_table`, whatever is sent: the sheet appends, so each run adds only the emails not exported yet. | default: `true` |
| `email_filter` | [EmailFilter-Input](https://api.sheetgo.com/rest/reference/models/EmailFilter-Input.md), nullable | no | Only read the emails that match these conditions. `attachment_size` is not available for Gmail. Omit to read every email (each run scans at most 1000). |  |
| `columns` | array of [EmailColumn](https://api.sheetgo.com/rest/reference/models/EmailColumn.md), nullable | no | With `extract=fields_table`, the columns the sheet gets: any of `date`, `from`, `to`, `cc`, `bcc`, `subject`, `body`, `body_html`, `attachments`, `message_id`, `labels`. `date` is always among them, sent or not: every row carries its email's date. They are written in that order, whatever order they are sent in. Omit for every column. Refused with any other extract mode. | min items: 1 |
| `name` | string, nullable | no | Label for the source. Defaults to `Gmail`. |  |

## Used by

- [POST /rest/beta/automations/](https://api.sheetgo.com/rest/reference/automations.md#post-rest-beta-automations)
- [PUT /rest/beta/automations/{id}](https://api.sheetgo.com/rest/reference/automations.md#put-rest-beta-automations-id)
- [AutomationCreate](https://api.sheetgo.com/rest/reference/models/AutomationCreate.md)
- [AutomationReplace](https://api.sheetgo.com/rest/reference/models/AutomationReplace.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.