> ## Documentation Index
> Fetch the complete documentation index at: https://traddal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect a mailbox (Outlook / Gmail)

> Receive customer email in the Inbox and send from your own address by connecting Outlook or Gmail in Apps.

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.

```bash theme={null}
cd apps/api
wrangler secret put MICROSOFT_CLIENT_ID
wrangler secret put MICROSOFT_CLIENT_SECRET
wrangler secret put MICROSOFT_CLIENT_ID --env staging
wrangler secret put MICROSOFT_CLIENT_SECRET --env staging
```

### 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`

```bash theme={null}
cd apps/api
wrangler secret put GOOGLE_CLIENT_ID
wrangler secret put GOOGLE_CLIENT_SECRET
wrangler secret put GOOGLE_CLIENT_ID --env staging
wrangler secret put GOOGLE_CLIENT_SECRET --env staging
```

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).