Gmail

The Gmail trigger polls a Google account's Gmail inbox at a configurable cadence and fires the workflow once per new message that matches your filter. Built on the OAuth credential system; no IMAP password required.

How to configure

1. Connect a Gmail credential to this workflow first. Open Workspace → Credentials, choose Add Google account, and grant the https://www.googleapis.com/auth/gmail.readonly + https://www.googleapis.com/auth/gmail.modify scopes (modify is needed only if you toggle Mark as read). The trigger uses the OAuth token to call the Gmail API on your behalf — no IMAP password needed.
2. Gmail does not push events here. Instead, MyBotBox's scheduler polls Gmail at the cadence you configure (5/15/30/60 minutes — default 5m). On each tick the platform calls users.messages.list with your filter (subject/sender/label/has-attachment) and dedupes on Gmail's message ID. The first poll after creation establishes the baseline (no historical fires).
3. Each new message fires the workflow once. Downstream blocks read <gmail1.email.subject>, <gmail1.email.from>, <gmail1.email.bodyText>, <gmail1.email.attachments>. Attachments larger than 25 MB are dropped (Gmail's API limit); smaller ones are uploaded to signed-URL storage that expires in 24 hours.
4. To verify, send a test email matching your filter from another account. Expect a fire within one cadence interval. To force an immediate poll, point the dispatcher at this workflow per the triggers runbook:

curl -X POST -H "x-scheduler-key: $POLL_DISPATCH_SECRET" \
  'https://mybotbox.com/api/webhooks/poll/dispatch?tier=5m'

Authentication

OAuth-only via your connected Google credential. Required scopes:

The trigger refreshes the access token on every poll using the stored refresh token — credentials never need re-prompting under normal use.

Sample payload

{
  "email": {
    "id": "18d4e5f6a7b8c9d0",
    "threadId": "18d4e5f6a7b8c9d0",
    "subject": "Invoice #INV-2026-0427 — Yarlis AI",
    "from": "billing@yarlis.ai",
    "to": "alex@example.com",
    "cc": "",
    "date": "2026-04-26T21:00:00.000Z",
    "bodyText": "Your invoice for April is attached. Total due: $49.00.",
    "bodyHtml": "<p>Your invoice for April is attached. <strong>Total due: $49.00.</strong></p>",
    "labels": ["INBOX", "IMPORTANT", "CATEGORY_UPDATES"],
    "hasAttachments": true,
    "attachments": [
      {
        "filename": "invoice-2026-0427.pdf",
        "contentType": "application/pdf",
        "size": 84321,
        "attachmentId": "ANGjdJ8aBcDeFgHiJkLmNoPqRsTuVwXyZ",
        "signedUrl": "https://storage.googleapis.com/mybotbox-attachments/invoice-2026-0427.pdf?X-Goog-...",
        "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
      }
    ]
  },
  "timestamp": "2026-04-26T21:00:05.123Z"
}

Verifying a poller

Pollers don't expose an inbound webhook URL — there's no endpoint to POST a payload at. Instead, force-run the dispatcher and watch the workflow log. See apps/sat/tests/staging/triggers/pollers/README.md for the canonical recipe — the short version:

POLL_DISPATCH_SECRET=$(gcloud secrets versions access latest \
  --secret=poll-dispatch-secret --project=ystudio-core)

curl -X POST -H "x-scheduler-key: $POLL_DISPATCH_SECRET" \
  'https://mybotbox.com/api/webhooks/poll/dispatch?tier=5m'

Troubleshooting

• Trigger never fires — check that the OAuth credential includes gmail.readonly (re-authorize if missing). The first poll after creation only baselines; send a fresh email afterwards.
• Old emails fire on first save — the baseline poll establishes a cursor at "now"; older messages should not fire. If they do, you likely set the cadence to 60m and a new message arrived during the baseline window.
• consecutive_failures rising in mailbox_poller_state — usually expired refresh token. Re-authorize the credential in Workspace → Credentials.
• No attachment URLs — attachments >25 MB are dropped (Gmail API limit). Use the IMAP trigger for larger ones.