Skip to main content

Communication Channels

Connect a personal mailbox to Open Saasframe so the messages you send through the app go out under your real email address and replies land in the unified inbox alongside Slack, WhatsApp, and other channels.

This release ships two providers:

  • Gmail (personal + Google Workspace) — administrators: see Set up Gmail for the one-time OAuth (and optional Pub/Sub push) setup
  • IMAP + SMTP (Fastmail, iCloud, generic providers, on-prem mail servers) — see Set up IMAP + SMTP

There is no dedicated Microsoft 365 / Outlook connector; connect those mailboxes through IMAP + SMTP (see below).

When to use this vs Inbox Ops​

These two features look similar but solve different problems:

You want…Use
To send and receive messages from your own daily email addressCommunication Channels (this guide)
To forward customer threads into a shared mailbox so the AI agent extracts orders, quotes, and contactsInbox Ops

A tenant can use both. Communication Channels is per-user; Inbox Ops is tenant-shared. Inbox Ops never reads your personal mailbox, and Communication Channels never receives forwarded threads from your colleagues.

End-user flow​

1) Open your profile page​

Profile → Communication Channels (in the left sidebar). The page is empty until you connect a channel.

The CTA in the top right offers two providers. Pick the one that matches your mailbox.

2) Connect a channel​

Gmail​

  1. Click Connect Gmail.
  2. Google opens its OAuth consent screen.
  3. Accept the scopes Open Saasframe asks for (read/send/manage labels for Gmail; email + name for your profile).
  4. You return to the profile page; your Gmail address appears as the new channel.

The first poll runs within five minutes. New mail in your inbox label is synced; sent mail is captured automatically when you reply from inside Open Saasframe.

Microsoft 365 / Outlook​

There is no dedicated Microsoft connector. An Outlook.com / Microsoft 365 mailbox can be connected through IMAP + SMTP using an app password.

IMAP + SMTP​

  1. Click Connect IMAP.
  2. Open Saasframe opens an inline form asking for:
    • IMAP host / port / TLS mode / username / password
    • SMTP host / port / TLS mode / username / password
    • From address (must be deliverable by your SMTP server)
    • A security ack checkbox confirming you understand IMAP/SMTP basic auth is less secure than OAuth.
  3. Click Connect. Open Saasframe performs a live IMAP LOGIN and SMTP verify (EHLO + AUTH ping) against your servers. Bad credentials, wrong host, or unreachable ports are reported as field-level errors right there — nothing is saved until both servers accept the login.

Use a per-app password whenever your provider offers one (Fastmail, Yandex, etc.). Stored credentials are encrypted at rest.

3) Send mail from Open Saasframe​

Compose a message in the Messages inbox as usual. The platform routes the outbound through your primary channel automatically; the recipient sees the message coming from your real email address, complete with proper Message-ID, In-Reply-To, and References headers so it threads correctly in your sent folder and the recipient's inbox.

4) Manage multiple channels​

A user can have multiple channels connected simultaneously (e.g. a Gmail account and an IMAP-connected Fastmail account). One of them is marked primary — that's the channel used for outbound when you don't explicitly pick one. Click the star icon next to a channel to flip the primary.

5) Reconnect​

If a refresh token expires or a password rotates, the affected channel flips to Needs reconnection and you get a notification. Open the profile page and click Reconnect on the offending row. Gmail goes back through the OAuth flow; IMAP/SMTP shows the credentials form again pre-filled with the unchanged values.

While a channel is in Needs reconnection, outbound sends through it are blocked at the API layer with a clear inline error so you know exactly why a message wouldn't send.

6) Import older messages (optional)​

When you connect a mailbox, Open Saasframe deliberately starts with a clean slate — no historical mail is pulled in. This avoids "I connected my Gmail and waited 40 minutes for the app to scan my 1.2M-message inbox" failures on first connect. Going forward, every new message hits the unified inbox within ~60 seconds.

If you want older messages to appear too (for example to backfill a CRM contact's email history), open Profile → Communication Channels, find your channel, and click Import history. A dialog asks for three things:

FieldWhat it does
Look back (days)How far back to scan, between 1 and 365. Default is 30.
Filter by sender (optional)Comma-separated list of email addresses. Restricts the scan to messages from those senders only. Leave empty to scan every sender in the window.
Maximum messagesHard cap on how many messages to import, between 1 and 5000. Default is 500.

Press Cmd/Ctrl+Enter to submit (or Escape to cancel). The import runs in the background — you'll see a progress indicator in the top bar showing how many messages have been processed. You can close the page and come back later; the import keeps running.

Tips:

  • Filtering by sender is much faster than scanning the whole window, because the IMAP / Gmail server narrows the search before sending any message bodies.
  • Importing is idempotent. If you re-run an import that overlaps with already-synced mail, duplicates are skipped automatically.
  • Only one import per channel at a time. Trying to start a second import while the first is running returns a friendly error — wait for the first to finish or hit "Cancel" on the progress bar.
  • IMAP today; Gmail in a follow-up release. The "Import history" button is disabled on Gmail channels until Spec C ships its adapter support.

7) How fast does new mail appear? (Push delivery)​

For Gmail accounts, Open Saasframe uses push delivery instead of polling: the provider tells us the moment new mail arrives, so the unified inbox typically updates within 5–15 seconds. There's nothing to configure — push is enabled automatically when you connect a Gmail mailbox, provided your operator has set up the underlying infrastructure (a Pub/Sub topic for Gmail).

For IMAP accounts (Fastmail, custom servers, etc.), Open Saasframe polls every 60 seconds — IMAP doesn't expose push primitives that fit a queue-worker model. New mail usually appears within 30–60s.

If your channel's status drops from "Connected" to something else (e.g. your Pub/Sub topic gets misconfigured), Open Saasframe automatically falls back to 60-second polling. You'll see a "Re-register push" button in the channel detail page when this happens — clicking it tries to re-establish push delivery.

8) Disconnect​

Click Disconnect on a channel to halt polling and clear the stored credentials. The Open Saasframe action log records the disconnect, and an admin can undo within the standard undo window if you change your mind — except when another channel has become primary in the meantime (the platform won't silently demote it). Disconnecting does not delete the conversation history that was already synced; it just stops new mail from coming in or going out via that account.

Troubleshooting​

Gmail "App blocked: This app is not verified"​

You haven't verified your Google Cloud OAuth app yet. For internal use on a Workspace tenant, verification isn't required — but you must add yourself as a test user in OAuth consent screen → Test users while the app is in Testing status.

IMAP "Authentication rejected by server: 535 5.7.8"​

Your provider rejected the password. Most common causes:

  • Wrong password. Re-enter it.
  • Provider requires per-app password. Google, Fastmail, Yandex, and many others won't accept your account password directly when 2FA is enabled. Generate an app password from your provider's account settings.
  • IMAP/SMTP disabled. Some providers turn off IMAP by default; enable it in their account settings.

IMAP "Could not reach server: ECONNREFUSED"​

The host/port combination isn't reachable. Check the provider's documented IMAP host (usually imap.<provider>.com) and pick the right port for the TLS mode you selected (993 implicit TLS, 143 STARTTLS).

Channel shows "Needs reconnection" repeatedly​

The most common cause is a revoked refresh token (Gmail's refresh tokens are revoked when you change your password). Reconnect once and the new token persists.

If reconnects keep failing within minutes:

  • Confirm your Gmail OAuth client is configured with Access type: Offline and Prompt: consent (Open Saasframe sends these but custom client configs can override).

"Outbound delivery failed: requires_reauth"​

Same root cause as Needs reconnection. Open the profile page and reconnect the affected channel; the failed outbound is retried automatically on the next poll cycle.

Mail isn't appearing in the unified inbox​

  • Confirm the channel status is Connected in your profile.
  • Click Refresh on the channel row to force a poll outside the 5-minute cadence.
  • If you connected Gmail more than 7 days ago and haven't synced in that window, Open Saasframe falls back to a fresh inbox scan automatically — give it one poll cycle (5 minutes) to re-establish the cursor.

What Open Saasframe never does​

  • Reads mail outside your Inbox folder. Drafts, sent items written from your native client, and archived mail are not synced.
  • Reads private headers like Authentication-Results or DKIM-Signature for purposes other than delivery diagnostics.
  • Shares your mailbox content with other tenant users unless you explicitly assign a thread to them.
  • Sends mail without your action. Outbound only fires when you (or a workflow you set up) explicitly composes and sends.

If you ever want to know exactly which messages have been synced from your account, the channel detail page lists every message-id Open Saasframe has on file.