IMAP Email

The IMAP trigger polls any IMAP server (Gmail, Outlook, Yahoo, iCloud, Fastmail, custom) and fires the workflow once per new message. Gmail and Outlook can use OAuth (recommended); every other provider uses an app password.

How to configure

1. Pick your Provider. Gmail and Outlook autofill IMAP host/port and support OAuth (recommended — pick a connected Google or Microsoft account). All other providers require an App password: generate one in the provider's account-security settings (e.g. Google App Passwords, Yahoo Generate app password, iCloud App-Specific Passwords) — your account password will be rejected by IMAP+2FA accounts.
2. For Custom IMAP, fill in IMAP host + Port (default 993 for IMAPS). Leave Use TLS on unless your server only supports STARTTLS on a different port. Disable Reject invalid TLS certificates only for self-hosted servers with self-signed certs — never for public providers.
3. Pick the Mailbox (folder) to watch — defaults to INBOX. Set a Filter to limit fires: Unread only uses UNSEEN; From specific sender uses FROM; Subject contains… uses SUBJECT; Custom IMAP query takes a raw search expression (e.g. UNSEEN SINCE 1-Jan-2026 FROM boss@example.com). On the first poll the trigger baselines — no historical fires.
4. Cadence default is 5m (faster than Gmail OAuth pollers because IMAP UIDs are cheap). Verify by sending a test email matching the filter, or force an immediate dispatcher run per the triggers runbook:

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

Read fields via <imap1.subject>, <imap1.bodyText>, <imap1.attachments>.

Authentication modes

Sample payload

{
  "messageId": "<CABcDeFg123456@mail.example.com>",
  "uid": 48217,
  "subject": "Re: Pricing for the enterprise tier",
  "from": "sales-prospect@bigco.com",
  "to": "alex@example.com",
  "cc": "manager@example.com",
  "date": "2026-04-26T20:30:00.000Z",
  "bodyText": "Following up on our call — we're ready to move forward with the pilot.",
  "bodyHtml": "<p>Following up on our call — we're <strong>ready to move forward</strong> with the pilot.</p>",
  "attachments": [
    {
      "filename": "pilot-agreement.pdf",
      "contentType": "application/pdf",
      "size": 142391,
      "signedUrl": "https://storage.googleapis.com/mybotbox-attachments/imap/pilot-agreement.pdf?X-Goog-...",
      "sha256": "8a1f72b6b3f4e6d0c2a5e1f7b9d4c6e8a3f5b7d9e1c3a5f7b9d1e3c5a7f9b1d3"
    }
  ],
  "headers": {
    "message-id": "<CABcDeFg123456@mail.example.com>",
    "from": "sales-prospect@bigco.com",
    "to": "alex@example.com",
    "cc": "manager@example.com",
    "subject": "Re: Pricing for the enterprise tier",
    "date": "Sat, 26 Apr 2026 20:30:00 +0000",
    "in-reply-to": "<original-thread-id@mail.example.com>"
  },
  "mailbox": "INBOX"
}

Verifying a poller

IMAP triggers are poller-only — there is no inbound webhook URL. Force-run the dispatcher per apps/sat/tests/staging/triggers/pollers/README.md:

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

• Authentication failed — most public providers reject account passwords on IMAP when 2FA is enabled. Use an app password (or OAuth on Gmail/Outlook).
• Custom server TLS errors — self-signed cert? Disable Reject invalid TLS certificates only for trusted internal hosts.
• Trigger fires repeatedly on the same email — searchPreset: unread_only plus a downstream block that doesn't mark messages read. Toggle Mark as read after firing on, or pick a different filter.
• Custom IMAP query rejected — search expressions must be valid RFC 3501 IMAP4 syntax. Use the Gmail IMAP search docs as a starting point for Gmail-style queries.