# Google and Microsoft email setup

Mailbox authorization is separate from signing in to Ralti.

Users connect mailboxes through Email → Add account. Configure provider applications on the server before offering their authorization buttons. Use the application’s exact HTTPS origin and register the corresponding callback URI with each provider. A Google or Microsoft sign-in method in Clerk does not grant Ralti access to email.

| Provider | Server configuration | Registered callback |
| --- | --- | --- |
| Google | GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI | https://app.your-domain.example/api/email/google/callback |
| Microsoft | MICROSOFT_CLIENT_ID, MICROSOFT_CLIENT_SECRET, MICROSOFT_TENANT_ID, MICROSOFT_REDIRECT_URI | https://app.your-domain.example/api/email/microsoft/callback |

## Use the implemented delegated scopes

Google uses https://www.googleapis.com/auth/gmail.modify. Configure a Google OAuth Web client, consent screen, test users or the applicable production verification, and the exact callback. Gmail’s restricted scope requires the provider’s relevant review before broad external access. Microsoft personal-mail connections request offline_access, User.Read, Mail.ReadWrite, and Mail.Send. Shared-mailbox connections use Mail.ReadWrite.Shared and Mail.Send.Shared with offline_access and User.Read.

A Microsoft shared mailbox also requires the connecting account’s Exchange delegation. Full Access enables reading; Send As or the applicable Send on Behalf permission enables the corresponding sending behavior. OAuth consent alone does not assign those mailbox permissions. Ralti binds a connection to the selected mailbox and keeps it private to its connecting member until they explicitly share a conversation or grant an agent access.

## Preserve the credential encryption key

```bash
openssl rand -base64 32
```

Store the generated value privately as ATLAS_EMAIL_ENCRYPTION_KEY. OAuth tokens and IMAP credentials use AES-256-GCM with purpose/workspace/actor/connection binding. The key must remain stable across migrations and restores; missing or invalid encryption has no plaintext fallback.

> **Validate real behavior** Test connect, callback return, refresh, sync, draft review, and an explicitly authorized synthetic delivery for each offered provider. Polling is bounded; Google push and IMAP IDLE are not implemented. Received attachments can be identified, but attachment downloads and outgoing attachments are not implemented. An accepted send does not prove recipient delivery.