SOURCE_ID: import_from_gmail NAME: Import Emails from Gmail CATEGORY: First-party Import emails from the connected Gmail account into Floqer, either as a one-time import of every matching email or as an ongoing source that re-syncs new emails on a schedule. Each email becomes a row with its headers, snippet, labels, attachment names and (optionally) its body. Imported rows become available to your Floqer workflows for routing, enrichment, reply handling, and the like. 1. ENDPOINTS Source identifier (used in every endpoint path): `import_from_gmail`. POST /api/v1/sources/import_from_gmail/preview Scope: sources:read Returns up to 10 sample email rows matching the search query and labels, without creating anything. Use this to validate the filter and inspect row shape before committing. POST /api/v1/sources/import_from_gmail Scope: sources:write Creates the source, imports every matching email, and — for an active source — keeps importing new emails on a schedule. Returns `source_instance_id` (the new source's UUID). POST /api/v1/sources/import_from_gmail/options/labels Scope: sources:read Resolves the Gmail labels of the connected account (see §4). GET /api/v1/sources//data Scope: sources:read Paginated rows imported into the created source. `` is the UUID returned by Create. Query: `page_no` (default 1), `page_size` (default 20, max 200). Source-agnostic; see concepts.txt §10. POST /api/v1/sources//sync Scope: sources:write Connects the created source to a workflow and (by default) backfills it with the source's current rows. `` here is the UUID returned by Create. Body: { workflow_id, field_mapping, push_existing?, run? } — `field_mapping` keys are `input.` references on the target workflow, values are the source fields to pull. This step is source-agnostic; see concepts.txt §10 for the full shape. PATCH /api/v1/sources//status Scope: sources:write Pause or resume an active source by UUID. Body: {"status": "active" | "paused"}. Source-agnostic. Every endpoint for this source first verifies the API-key user has an active Google connection. Missing connection → 424. 2. BODY SHAPE (PREVIEW + CREATE) Field names are snake_case. Unknown top-level keys are rejected with 400 — the body is strict. Preview accepts: query optional: Gmail search query labels optional: array of Gmail label IDs include_body optional boolean (defaults to false) Create accepts all the preview fields plus: name required: display name for the new source max_count optional positive integer: most emails to import per run; omit to import every matching email import_type "static" | "active"; optional (defaults to "static") frequency cron string; required when import_type === "active"; not allowed for static expiration_date ISO date in the future; optional, active only; not allowed for static 3. FIELD CATALOGUE query (string) — optional Gmail search query using Gmail's own search operators, e.g. "from:billing@acme.com is:unread", "subject:invoice has:attachment", "newer_than:30d". Omit it (and `labels`) to import the whole mailbox. labels (string[]) — optional Gmail label IDs to filter by (e.g. "INBOX", "Label_123"). An email must carry every listed label to match. Resolve IDs with the `labels` dynamic-options call (§4) — the option `value` is the label ID. include_body (boolean) — optional, defaults to false When true, each row also carries the email body as `body_text` and `body_html`. name (string) — required on create only Human-readable display name for the source. max_count (integer) — optional, create only Most emails to import per run (the initial import and each sync of an active source). Omit it to import every matching email; with no `query` or `labels` that is the whole mailbox, so set a cap when you only need a sample. import_type (string) — optional, create only "static" (default): one-time import of every matching email. "active": initial import plus a recurring sync of new matching emails on the `frequency` cron until `expiration_date`. frequency (string) — required on create when import_type === "active" Cron string for the re-sync cadence (e.g. "0 * * * *"). Not allowed when import_type is "static". expiration_date (string) — optional, active only ISO date in the future after which an active source stops syncing. Not allowed when import_type is "static". Row fields on imported emails: uid (stable per-email id), message_id, thread_id, rfc_message_id, rfc_thread_id, in_reply_to, is_reply, from, from_name, to, cc, bcc, subject, snippet, date, labels, has_attachments, attachment_names, and — with `include_body: true` — body_text, body_html. 4. DYNAMIC OPTIONS One dynamic-options field name is available for this source. POST to /api/v1/sources/import_from_gmail/options/labels with body `{}`. labels Context: none. Returns: {value: , label: } for each label in the connected Gmail account (system labels such as INBOX and SENT, plus the user's own labels). Use the returned `value`s directly inside `labels[]`. Connection check: the call verifies the API-key user has an active Google connection first. Missing connection → 424. 5. HOW TO CONFIGURE END-TO-END Typical flow for an AI agent building a Gmail import source: Step 1 — (Optional) Resolve the labels POST /api/v1/sources/import_from_gmail/options/labels Body: {} Pick the label `value`s (label IDs) you want to filter by. Step 2 — Preview before committing POST /api/v1/sources/import_from_gmail/preview Body: { "query": "from:billing@acme.com", "labels": ["INBOX"], "include_body": false } Check the returned `data[]` row shape (up to 10 sample emails) and `metadata.total_results` (approximate number of matching emails). Iterate on the filter until you're happy — preview never creates anything. Step 3 — Create the source POST /api/v1/sources/import_from_gmail Body: + the create-only fields: "name": "", "max_count": 500, // optional cap per run "import_type": "static" | "active", "frequency": "0 * * * *", // only when import_type=active "expiration_date": "2027-01-01" // optional, active only Response: { "status": 201, "data": { "source_instance_id": "", "name", "created_at" }} Step 3b — (Optional) Poll imported rows while the import runs GET /api/v1/sources//data?page_no=1&page_size=20 ( = UUID from Step 3) `total_count` grows as the import (and later syncs) bring in emails. Step 4 — Sync the source into a workflow (so its emails flow downstream) POST /api/v1/sources//sync ( = UUID from Step 3 ) First build `field_mapping`: a. GET /api/v1/workflows → pick the destination workflow_id. b. GET /api/v1/workflows//sheets//inputs → each input has a `reference` like `{{input.email}}`. c. Map each workflow input (reference WITHOUT braces) to a source field — the source fields are the row fields listed in §3. Body: { "workflow_id": "", "field_mapping": { "input.email": "from", "input.subject": "subject" }, "push_existing": true, "run": "all" } See concepts.txt §10 for the full sync semantics (source-agnostic). The import runs asynchronously — the create call returns as soon as the source is created and the import has started, not when emails have finished arriving. 6. KEY NOTES - Google connection is mandatory. If the API-key user has no active Google connection, every endpoint (preview, create, options) returns 424 ("User is not connected to 'googleSheets'."). Surface this as a "connect Google first" CTA. - If the Google connection exists but can't read Gmail (access was revoked, or Google was connected without Gmail access), preview, create and the labels call return 424 and ask the user to reconnect Google with Gmail access. Create checks this before creating anything. - `query` and `labels` combine: an email must match the query AND carry every listed label. With neither set, the source imports the whole mailbox, up to `max_count` if set. - Preview returns at most 10 sample rows; `metadata.total_results` is Gmail's approximate count of all matching emails. - An active source imports only emails that are new since its previous sync, so each email appears once. - `import_type` defaults to "static" (one-time import). `frequency` and `expiration_date` are only valid when `import_type: active` — sending either with a static import is a 400. - Use PATCH /status to pause an active source and resume it later without recreating it. 7. WHERE IT FITS UPSTREAM (in Gmail) Emails live in the mailbox of the user's connected Google account. THIS SOURCE Creates a Gmail import source. On creation it imports every email that matches the query and labels; an active source also syncs new matching emails on the `frequency` cron until `expiration_date`. DOWNSTREAM (in Floqer) Imported emails become available to your Floqer workflows — wire the source into a workflow to route inbound requests, extract leads or intent, or trigger follow-ups. 8. WHEN TO USE - One-time import of a set of emails (e.g. every message from a domain or with a label) into a Floqer workflow: `import_type: static`. - Keep an inbox or label syncing into a workflow on a schedule (e.g. parse inbound demo requests or replies as they arrive): `import_type: active`, `frequency: "0 * * * *"`. Last updated: 2026-10-29. Reference: https://floqer.com/docs/reference