Skip to main content
Traddal ships every organization a <alias>@traddal.email address. Connecting your own mailbox from Apps lets customer mail land in the Inbox and lets pre-alerts, flow emails and replies go out from your real address. Both providers work the same way: OAuth in a popup, an encrypted refresh token at rest, and a per-mailbox sync that polls for new Inbox mail (Outlook also gets push notifications).

​
For tenants

  1. Open Apps → Outlook or Gmail → Install (or Add mailbox to connect another account).
  2. Sign in and accept the permissions. Outlook can also connect a shared mailbox (sign in with a work account that has Full Access + Send As on it).
  3. New mail in that mailbox appears in Inbox within seconds; replies go back through the same account on the same conversation.
  4. To send flow emails and pre-alerts from the mailbox, pick it under Settings → Notifications → Sender.
If access is revoked or expires, the app card shows Reconnect; until then outbound mail falls back to the traddal.email alias so nothing is dropped.

​
Platform setup (operators of the Traddal deployment)

Both providers need an OAuth client registered once per environment and its credentials stored as Worker secrets. Nothing works until these are set — the app card reports “not configured”.

​
Microsoft (Outlook)

  1. Entra admin center → App registrations → New. Supported account types: Accounts in any organizational directory and personal Microsoft accounts.
  2. Authentication → Web redirect URIs:
    • https://api.mytraddal.com/public/apps/outlook/callback
    • https://api.mytraddal-staging.com/public/apps/outlook/callback
    • http://localhost:8787/public/apps/outlook/callback
  3. API permissions (delegated): offline_access, User.Read, Mail.Send, Mail.ReadWrite (+ Mail.Send.Shared, Mail.ReadWrite.Shared for shared mailboxes).
  4. Certificates & secrets → new client secret.

​
Google (Gmail / Google Workspace)

  1. Google Cloud Console → create/select a project → APIs & Services → Library → enable the Gmail API.
  2. OAuth consent screen: External, app name “Traddal”, support + developer emails, authorized domain mytraddal.com. Add scopes https://www.googleapis.com/auth/gmail.readonly and https://www.googleapis.com/auth/gmail.send. While the app is in Testing, only listed test users can connect and refresh tokens expire after 7 days — publish the app (Gmail scopes are restricted, so Google runs a verification review before it’s public).
  3. Credentials → Create credentials → OAuth client ID → Web application. Authorized redirect URIs:
    • https://api.mytraddal.com/public/apps/gmail/callback
    • https://api.mytraddal-staging.com/public/apps/gmail/callback
    • http://localhost:8787/public/apps/gmail/callback
For local development put both pairs in apps/api/.dev.vars. Optional OUTLOOK_REDIRECT_URI / GMAIL_REDIRECT_URI override the callback URL the Worker derives from its public origin.

​
Platform registry

The platform admin’s app catalogue (reference.platform_apps) gates each provider: a coming_soon row hides Install. Flip Gmail to enabled once the Google client is verified.

​
How sync works

Each connected mailbox gets its own Durable Object (OUTLOOK_SYNC / GMAIL_SYNC) that keeps the provider cursor (Graph delta link / Gmail history id) and polls adaptively (20 s after activity → 3 min idle). The baseline on connect replays the last 2 hours only. The per-minute cron simply re-ensures every connected mailbox has a running DO. Inbound mail runs through the same pipeline as traddal.email mail (threading, agents, auto-drafts).