Docs / Inbox, calendar and Drive
Unified inbox
The unified inbox brings mailboxes your members already have elsewhere (Gmail, Outlook.com and Microsoft 365, iCloud, Yahoo, AOL, Fastmail, Zoho Mail, GMX, Proton Mail through Bridge, or any IMAP server) into the inbox, next to mail on your own domains. Mail syncs both ways: what you read, star, archive or delete here is the same in the mailbox. Replies and new messages go out through the same account, and are saved to its Sent folder.
It also receives mail for your domains from sending providers that offer inbound mail (Resend, Mailgun, Amazon SES, Postmark, SendGrid and Cloudflare Email Routing). See Provider inbound.
Connect accounts in Settings → Connected accounts (also at /accounts). Connected accounts are available on self-hosted servers and in the free desktop app, not on the hosted cloud edition (see Availability). In the inbox, the Accounts section of the sidebar shows All inboxes, Your domains and each account with its folders. Messages from an account carry a small badge with its name.
Supported providers
| Provider | How it connects | Sync | Sending | Notes |
|---|---|---|---|---|
| Gmail and Google Workspace | "Connect Google" (Gmail API, OAuth), or IMAP with an app password | Gmail API history; IMAP: UIDs | Gmail API, or SMTP (smtp.gmail.com) | IMAP needs 2-Step Verification and an app password. Workspace admins can turn app passwords off. Gmail saves sent mail itself. |
| Outlook.com, Hotmail | "Connect Microsoft" (Microsoft Graph, OAuth) | Graph delta queries | Graph sendMail | Outlook.com requires OAuth for IMAP and SMTP; a password does not work. |
| Microsoft 365 (work or school) | "Connect Microsoft" | Graph delta queries | Graph sendMail | Exchange Online turned off password sign-in for IMAP, and SMTP AUTH with a password is off by default from December 2026 (Microsoft message center MC786329). |
| Zoho Mail | "Connect Zoho" (Zoho Mail API, OAuth), or IMAP | Zoho Mail API; IMAP: UIDs | Zoho API, or SMTP | IMAP access must be turned on in Zoho Mail settings. Personal and free: imap.zoho.com; paid with your own domain: imappro.zoho.com; other data centers use the host shown in Settings → Mail Accounts. With two-factor sign-in, use an application-specific password. |
| iCloud Mail | IMAP | IMAP | SMTP (smtp.mail.me.com:587) | imap.mail.me.com:993. An app-specific password is required. The user name is the part before @icloud.com. |
| Yahoo Mail | IMAP | IMAP | SMTP (smtp.mail.yahoo.com:465) | imap.mail.yahoo.com:993. Generate an app password in Account Security. |
| AOL Mail | IMAP | IMAP | SMTP (smtp.aol.com:465) | imap.aol.com:993. Generate an app password in Account Security. |
| Fastmail | IMAP | IMAP | SMTP (smtp.fastmail.com:465) | imap.fastmail.com:993. Third-party apps need an app password; Basic plans do not include IMAP. |
| GMX | IMAP | IMAP | SMTP (mail.gmx.com:587) | imap.gmx.com:993. Allow IMAP in GMX settings. |
| Proton Mail | IMAP through Proton Mail Bridge | IMAP | SMTP through Bridge | Paid Proton plans. Bridge must run where this server can reach it (default 127.0.0.1:1143 IMAP and :1025 SMTP, STARTTLS with Bridge's own certificate). A Bridge on a private address needs ONESEND_ALLOW_PRIVATE_SMTP=true. |
| Any IMAP server | IMAP | IMAP (CONDSTORE when offered) | SMTP | Port 993 is implicit TLS; 143 uses STARTTLS. |
Server names, ports and app password rules were checked against each provider's help pages on 2026-11-08. Providers change them; the wizard lets you edit every setting.
The OAuth clients behind "Connect Google / Microsoft / Zoho" are yours: see OAuth apps for connected mailboxes for creating them and the GOOGLE_*, MICROSOFT_* and ZOHO_* variables (Self-hosting).
Availability
ONESEND_CONNECTED_ACCOUNTS (on or off; also connectedAccounts in onesend.config.json) decides whether a server offers connected accounts. It is on by default on self-hosted servers and off on the cloud edition (ONESEND_EDITION=cloud). Personal mailboxes connect in the Mac app or on a self-hosted server, which sync directly with the mail provider. The Cloudflare edition reads the same variable.
When it is off:
GET /v1/accountsanswers{ "data": [], "available": false }. Every other/v1/accounts…endpoint, the Google, Microsoft and Zoho sign-in and its callback, and the push notification hooks (/hooks/accounts/…) answer 403 with the error codeconnected_accounts_unavailable.- The sync engine and IMAP IDLE do not run, and sending from a connected account is refused.
- Sending providers that send through a personal mailbox (
gmail_api,microsoft_graph,zoho_mail_apiandmailbox) cannot be created or resumed. SMTP connections to your own mail server are allowed. - Accounts connected earlier are paused at startup, with their sending providers. Their mail and settings are kept; turning the variable on again lets you resume them.
GET /v1/auth/mereportscapabilities.connectedAccounts: false; the dashboard then shows a short explanation instead of the connect buttons and hides the mailbox provider types.
Provider inbound for your own domains, the agent inbox and the IMAP and POP servers for workspace mailboxes are not affected.
Storage: full or index only
Each account has a storage mode, chosen when you connect it (Index only in the connect dialog, or storage in POST /v1/accounts and in the OAuth start request) and changed later with Store message bodies on the account or PATCH /v1/accounts/{id} { "storage": "full" | "index" }.
| Mode | Stored here | Bodies |
|---|---|---|
full (default) | Headers, flags, folders, labels, the snippet, the body (text and HTML), attachments and the message source | Read from the database |
index | Headers (From, To, Cc, Subject, Date, Message-ID, References), flags, folders and labels, remote ids, the snippet, the size, attachment names, types and sizes | Fetched from the mailbox when needed |
In index mode, the body is fetched from the mailbox (the connector's fetchMessage: IMAP, Gmail API, Microsoft Graph or Zoho Mail API) when someone opens the message in the dashboard or with GET /v1/inbox/messages/{id} or GET /v1/inbox/threads/{id}, when a mail app downloads it, when the AI assistant or an MCP client reads the conversation, and when a reply quotes it. Fetched bodies are kept in a small in-memory cache (five minutes, 32 MB per process) and are never written to the database.
- If the mailbox cannot be reached, opening the message answers 502
mailbox_unavailable("Could not reach the mailbox …") and the dashboard offers Try again. Lists still work, and a conversation shows such a message with its snippet andbodyUnavailable: true. The AI assistant then uses the snippet, and a reply quotes the snippet. - Rules, Important/Other sorting, subscription tracking and look-alike warnings run at sync time on the headers and the snippet.
- Search covers headers and the snippet only.
- Switching
full→indexdeletes the stored bodies, attachment content and sources of the account in a background job; nothing changes in the mailbox. Switchingindex→fullfetches the bodies of the messages in the sync window again in a background job; older messages stay index-only and are still opened from the mailbox. - Retention pruning, workspace deletion and exports handle index-only messages like any other; an export marks them
"storage": "index".
Stored mail of both modes is encrypted at rest (see Mail encryption).
Connecting an IMAP account
- Settings → Connected accounts → Add IMAP account.
- Pick the provider. The server settings and the link to create an app password are filled in.
- Enter the address and the app password (or password). Test and continue signs in and lists the folders. Nothing is stored yet.
- Choose how far back to bring in mail (7, 30 (default), 90 or 365 days), the folders to sync (Inbox, Sent, Spam, Trash and Archive by default), whether to share the account with the workspace, and whether to keep an index only (see Storage).
- Connect. The first sync starts at once.
With the API:
curl -X POST http://localhost:3000/v1/accounts -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '{
"provider": "imap", "preset": "icloud", "address": "ann@icloud.com", "username": "ann", "password": "abcd-efgh-ijkl-mnop",
"syncWindowDays": 30, "shared": false, "storage": "full" }'
POST /v1/accounts/test takes the same body and only checks it. GET /v1/accounts/providers lists the presets with their help links.
| Method | Path | Purpose |
|---|---|---|
| GET | /accounts | Accounts you can see, with status, last sync, last error, unread count and storage; available: false when the server does not offer connected accounts. |
| POST | /accounts, /accounts/test | Connect an IMAP/SMTP account; test settings without saving. |
| GET, PATCH, DELETE | /accounts/{id} | Read; change the name, sharing, sync window, poll interval, credentials, servers, status (active, paused), sendingEnabled, dailyLimit, storage (full, index); disconnect (?keepMessages=true keeps the copies). A new IMAP or SMTP host, port or secure needs password (and smtpPassword, when one is stored) in the same request: the stored password is never sent to a new server (400 credentials_required); the move is audited as account.destination_changed. API keys change accounts only with the admin scope. |
| GET, PATCH | /accounts/{id}/folders | Remote folders and labels, and which are synced. |
| POST | /accounts/{id}/sync | Sync now. wait: true runs it in the request and returns the counts; full: true syncs the whole window again (copies are matched, not duplicated). |
The SDK has onesend.accounts.* and onesend.inboundEndpoints.*; the MCP server has list_accounts, sync_account, and account on search_inbox and accountId on compose_email.
How sync works
- Initial sync brings in the last
syncWindowDaysdays, newest first, in pages. Older mail stays in the mailbox. - New mail arrives within seconds for IMAP accounts while the worker holds an IDLE connection (up to
ONESEND_ACCOUNTS_IDLE_MAXper process). Other accounts are polled every 2 minutes (Zoho: 5 minutes, because of its API limits), and accounts with IDLE are also polled every 15 minutes in case a notification was missed. - Incremental sync uses what the server offers: IMAP UIDs, CONDSTORE modification sequences, the Gmail history id, Microsoft Graph delta links or the Zoho API. If the server resets a folder (UIDVALIDITY changed, history too old), the folder is synced again and matched to the copies already here.
- Budgets. One run handles at most 300 new messages or 20 seconds of work, then continues in a new job, so a large mailbox never blocks other work.
- Duplicates. A message in two folders (IMAP copies) is one message here, matched by Message-ID within the account. The Sent copy of a message you sent from OneSend is matched to the sent message, so it is not shown twice.
- Threads. Messages join conversations through In-Reply-To and References across the workspace, so a reply that arrives in a connected account joins the conversation you started from your own domain. The provider's thread id (Gmail threads, Outlook conversations) is used when the headers are missing.
- Folders. Inbox → Inbox; Spam/Junk → Spam; Sent → the Sent view of the account; only in Trash → Trash; everything else (Archive, All Mail, your own folders) → Archive. Each account's folders are in the sidebar.
- Both ways. Read, starred, archive, move to Spam and delete are sent back to the mailbox. Delete moves the message to the mailbox's Trash; OneSend never expunges.
- Conflicts. The mailbox decides which folder a message is in: if you moved it in another app, it moves here too. For read and starred, the last change wins: a change you made here that was not sent back yet is kept, otherwise the mailbox's value is used.
- Removed mail. A message that is no longer in any synced folder is removed here (nothing else is deleted).
- Errors. Network trouble and rate limits are retried after 1, 2, 4… minutes, up to an hour. A rejected password or revoked sign-in stops syncing and shows Sign-in failed with a way to enter a new app password or sign in again. Errors are shown on the account and in the sidebar.
- Rules and sorting. Inbox rules (labels, assignment, spam, drop), Important/Other sorting, subscription tracking and look-alike sender warnings run on mail received in connected accounts. Rule webhooks, agent events and the
receivedevent run only for new mail of shared accounts, never for the initial sync. Outlook categories become the workspace label with the same name, when you have one.
Sending from a connected account
- Replies to a message from an account go out through that account. New message lists every account that can send in its From menu, with the provider's icon, next to your own addresses (in the web inbox and the Mac app alike); Write from … in the sidebar (or
POST /v1/inbox/composewithaccountId) writes a new message from it. - IMAP accounts send through their SMTP server, then save the message to the Sent folder with IMAP APPEND (Gmail saves sent mail itself). Gmail, Microsoft and Zoho accounts send through their API.
- Sent messages appear in the conversation and in Sent. Network failures are retried; a rejected message is marked failed with the server's reason.
- Test-mode API keys cannot send from connected accounts.
Sending provider
An account can also be a sending provider ("Personal mailbox"): turn on Use as a sending provider on the account. It is added to your default routing policy after your other providers, with a conservative daily cap (200 to 500 depending on the provider; change it with dailyLimit), and it only sends mail From its own address: other mail goes to the next provider. Gmail, Microsoft and Zoho accounts use their API adapters (gmail_api, microsoft_graph, zoho_mail_api); IMAP accounts use SMTP. Mailbox providers forbid bulk and marketing mail, so it is never used for campaigns.
Privacy
- Private by default. A connected account is private to the member who connected it: only that member sees its mail, in the dashboard, the API, search, conversations and Sent. Workspace owners and admins see that the account exists (address and status), not its mail. API keys only see shared accounts.
- Shared accounts behave like a team mailbox: every member can read and answer. Only the member who connected an account can share it.
- Passwords, app passwords and OAuth tokens are encrypted with
ONESEND_SECRET(and re-encrypted when you rotate it); they are never returned by the API. - Stored bodies, snippets, attachments and sources are encrypted at rest with the workspace's key (Mail encryption). With index-only storage, bodies are not stored at all.
- The AI and MCP privacy settings (codes hidden, Spam and Trash hidden, sending off) apply per account the same way as per mailbox. See Inbox → AI and app access.
- Disconnecting removes the stored credentials and the copies here. The original mailbox is not changed. Revoke OAuth access at the provider too if you want.
- Mail server hosts are user input: private and loopback addresses are refused unless
ONESEND_ALLOW_PRIVATE_SMTP=true, and passwords are only sent over TLS to public servers.
Limits
- 100 connected accounts per workspace.
- Messages larger than 25 MB are listed with their headers but their body is not copied; open them in the original mailbox.
- The source of synced mail is kept for mail apps and downloads and pruned after
ONESEND_RETENTION_DAYS, like received mail (index-only accounts keep no source). - Search on encrypted bodies matches whole words only; index-only accounts are searched by headers and snippet.
- Gmail API: per-user quota units; Microsoft Graph: throttling per mailbox; Zoho: 30 requests a minute per user. OneSend backs off when a provider limits it.
Cloudflare edition
ONESEND_CONNECTED_ACCOUNTS works the same on the Cloudflare edition (off when ONESEND_EDITION=cloud). The Cloudflare Workers edition cannot open raw TCP connections from its sync jobs, so IMAP accounts are not available there (the connector is only registered by the Node.js server; POST /v1/accounts with provider: imap answers provider_unavailable). Gmail, Microsoft and Zoho accounts work, because they use HTTPS APIs, and so does provider inbound. To sync IMAP accounts, run the Node.js server (it can share the database).
Provider inbound
If your domain's MX points to a sending provider, the provider can post received mail to OneSend. Create one connection per provider in Settings → Connected accounts → Inbound from sending providers (admins). Each gets a webhook URL with a secret token, shown once; New URL replaces it.
Mail goes through the normal pipeline (mailboxes, plus addresses, catch-all, rules, threads, look-alike check, Important/Other, agent events and webhooks), only for the workspace that owns the URL, and only for recipients on your verified domains with inbound turned on (any mode other than None; Provider is the one to choose).
| Provider | Setup | Verification | Content |
|---|---|---|---|
| Resend | Turn on Receiving for the domain; add a webhook for email.received with the URL. | Svix signature with the webhook signing secret | The webhook has metadata only; OneSend reads GET /emails/receiving/{id} with your API key and downloads the original from raw.download_url. |
| Mailgun | A route with forward("<URL>"); the URL ends in /mime so Mailgun posts body-mime. | timestamp + token HMAC with the HTTP webhook signing key | Full MIME (or the parsed fields when the URL has no /mime). |
| Amazon SES | Receipt rule with an SNS action (Base64), SNS HTTPS subscription to the URL. | SNS signature (certificate from sns.<region>.amazonaws.com), topic ARN | Up to 150 KB through SNS; SPF, DKIM and DMARC verdicts from SES; mail with a failed virus scan is not stored. The S3 action is not supported yet. |
| Postmark | Inbound stream webhook URL; turn on "Include raw email content". | Secret URL token | RawEmail, or the parsed fields and attachments. |
| SendGrid | Inbound Parse host with the URL and "POST the raw, full MIME message". | Secret URL token | email (raw), or the parsed fields and attachments. |
| Cloudflare | An Email Worker posts the raw message to the URL. (The OneSend Email Worker, the @onesend/inbound-cf workspace, posts to /ingest/cloudflare with ONESEND_INGEST_SECRET instead: see Receiving mail.) | Secret URL token | Raw message and Cloudflare's own authentication results. |
| Method | Path | Purpose |
|---|---|---|
| GET | /inbound-endpoints/providers | Setup steps and secrets per provider. |
| GET, POST | /inbound-endpoints | List; create (provider, secrets: apiKey, webhookSecret, signingKey, snsTopicArn; or connectionId to reuse a Resend sending provider's key). |
| PATCH, DELETE | /inbound-endpoints/{id} | Rename, change secrets, rotateToken; delete. |
The receiver is POST /ingest/{provider}/{id}/{token} (outside /v1). It answers 404 for an unknown URL, 401 for a bad signature, and 200 with ok: false when no domain of the workspace matches the recipients (so the provider stops retrying).