# Connect your mailbox

Three provider paths lead to the same place. Gmail and Microsoft Graph are consented through their own sign-in screens; any other server is connected with IMAP and SMTP details. Once a mailbox is attached it gets a role, a signature and its own autonomy, and its conversations appear on `#/inbox` alongside every other channel.

- **Status:** Available
- **Audience:** both
- **Channels:** email
- **In the app:** #/mailboxes, #/inbox
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/getting-started/connect-your-mailbox/

## Which path is yours

| Your mail lives on | Path | What you need to hand |
|---|---|---|
| Google Workspace or Gmail | Google OAuth plus the Gmail API | Permission to grant consent for that account |
| Microsoft 365 or Exchange Online | Microsoft Graph | Consent from the account, or an administrator who can grant it |
| Anything else | IMAP for reading, SMTP for sending | Host names, ports, and the mailbox's own credentials |

> **Note** Whatever the path, provider credentials are sealed on save and are never echoed back to a screen afterwards. A field that shows blank when you return to it is not a fault — it is the design, and it means a screenshot of the settings page cannot leak a secret.

## Attaching it

1. Open `#/mailboxes` and start adding a mailbox.
   - Result: You are asked which kind of account it is, which decides the path you take next.
2. For Gmail or Microsoft, complete the provider's own consent screen. For IMAP/SMTP, enter the server details for both directions — reading and sending are separate settings and can be separate hosts.
   - Result: The mailbox appears in the list. Connection is only the first claim; health is the one that matters.
3. Give the mailbox a role and a signature.
   - Result: The role is what distinguishes a sales address from a support one, and it is used when Connect decides which mailbox a reply belongs to. That choice is not editable from a held draft later, so it is worth getting right now.
4. Set the mailbox's own autonomy if it should differ from the channel's.
   - Result: You have created an endpoint-scoped rule, which beats the channel rule for this mailbox only.
5. Wait for the first sync, then open `#/inbox`.
   - Result: Conversations appear with senders resolved to people, not raw addresses — that resolution is what later lets a call and an email from the same person share one record.

## Proving it worked

'Connected' means the credentials were accepted. It does not mean mail is flowing, which is why the Mailboxes screen reports health separately. Two things are worth confirming before you trust the connection:

- **Recent messages, not just old ones.** A sync that fetched history but has stopped following new mail looks healthy in the conversation list and is not.
- **A message you can account for.** Send yourself something from another address and find it — that closes the loop between the provider and the canonical conversation record.

Mail deliberately exists twice inside Connect: the provider adapter stores what it fetched in the provider's own shape, and a bridge copies it into the canonical threads and messages the engine and the screens read. The engine never reads the provider tables. That is why adding a second provider later changes nothing about how anything downstream behaves.

## When it does not work

**Consent completes, no mail arrives** — The account consented but the required scopes were not all granted. Re-running consent is the fix; partial scopes fail quietly rather than loudly.
**IMAP reads, SMTP refuses** — Reading and sending are configured separately and frequently have different hosts, ports and rules. A mailbox in this state will draft and never send.
**Mail stops after a while** — The fetch cursor is the usual cause. [How a mail cursor loses messages](/research/cursor-loss/) explains the failure and how it is prevented.
**Everything works, nothing is sent** — Check autonomy before checking the mailbox. `draft_only` and `ask_before_send` both produce a written reply that stays put.
**Sending stops mid-day** — A plan's daily allowance can be spent. The approval is still recorded and the send waits rather than being lost.

An administrator who needs to see what a mailbox is doing has the decision log on `#/autonomy-audit`, which records refusals as well as actions — a refusal is a decision, and a mailbox that is quiet for a good reason looks identical to a broken one until you can see that reason written down.

## Questions

### Can I connect more than one mailbox?

Yes. A workspace can hold several, each with its own role, signature and autonomy. That is the normal shape for a business with separate sales, support and accounts addresses, and it is what makes endpoint-scoped rules useful — one address can be autonomous while another always asks.

### Does Connect move or delete my mail?

It reads, drafts and sends. Where the provider supports it, actions taken in Connect can be written back so your own mail client shows the same state. Deleting a conversation inside Connect marks the canonical record; it is not a way to empty your mailbox.

### What happens to a mailbox I remove?

The conversations already ingested stay — they are canonical records in your workspace, not a live view of the provider. What stops is fetching and sending through that account.

## Related

- [Your first hour](https://connectbyjbrh.com/docs/getting-started/first-hour/)
- [Email in Connect](https://connectbyjbrh.com/docs/email/)
- [Add a second mailbox](https://connectbyjbrh.com/docs/how-to/add-a-second-mailbox/)
- [Why 'connected' is not enough to prove mailbox health](https://connectbyjbrh.com/research/mailbox-health-beyond-connected/)
- [How a mail cursor loses messages, and how to stop it](https://connectbyjbrh.com/research/cursor-loss/)
- [Decide what Connect may do](https://connectbyjbrh.com/docs/getting-started/set-what-connect-may-do/)

## What this page is based on

- docs-source/sources/GENERAL.md §3, §4 — the data model and where things live
- Connect capability registry (docs-source/facts.py) — CHANNELS.email
- docs-source/sources/GENERAL.md §10 — sealed provider credentials