Docs / Inbox, calendar and Drive

Mail apps (IMAP, POP3 and SMTP)

Any inbox address can be read and answered from a mail app: Apple Mail, Outlook, Thunderbird, Mail on iPhone and iPad, the Gmail app and other Android mail apps. The mail app and the team inbox show the same mail: read state, stars, folders and labels change in both.

  • Username: the mailbox address, such as support@acme.dev.
  • Password: an app password created in the dashboard. Your OneSend account password is never accepted by IMAP, POP3 or SMTP.

Mail client access needs the Node.js server (npm start, Docker). It is not available on the Cloudflare Workers edition, which cannot accept IMAP or POP3 connections; there the settings page says so.

Set up a mail app

  1. In the dashboard, open Inbox → Addresses and choose Use in a mail app (phone icon) next to the address.
  2. Create an app password. Name it after the device ("Ann's iPhone"). Copy it: it is shown only once.
  3. Follow the steps for your mail app on the same page, or:
    • Apple Mail, iPhone and iPad: download the configuration profile and open it (Mac: System Settings → Privacy & Security → Profiles; iPhone: Settings → Profile Downloaded). The profile is unsigned, so the device labels it "Unsigned". It contains no password unless you tick the box to include the new one; then anyone with the file can read the mailbox, so delete the file after installing it.
    • Thunderbird: add a mail account with the address and app password. Thunderbird finds the servers by itself when autoconfig is set up; otherwise enter them by hand.
    • Outlook: add an account, choose IMAP under advanced or manual setup, and enter the servers.
    • Android: in the Gmail app choose Other → Personal (IMAP); in other apps choose manual setup and IMAP.
ServerPort (production)Port (default)Security
IMAPyour mail host9931993SSL/TLS
IMAPyour mail host1431143STARTTLS
POP3your mail host9951995SSL/TLS
POP3your mail host1101110STLS
SMTP (sending)your mail host5872587STARTTLS

The dashboard shows the ports this server actually uses. Use the same username and app password for incoming and outgoing mail.

App passwords

  • An app password belongs to one workspace member and opens the mailboxes chosen when it was created.
  • It is 16 random letters and digits, shown as xxxx-xxxx-xxxx-xxxx. Dashes, spaces and case do not matter.
  • It is stored as a scrypt hash and cannot be shown again. Revoke it on the same page; mail apps using it are signed out within five minutes. Removing a member from the workspace, or deleting the mailbox, also stops it.
  • The page shows when each one was last used, from which address and over which protocol.
  • 10 failed sign-ins for an address, or 30 from one IP address, block further attempts for a few minutes.

API: GET /v1/inbox/mailboxes/{id}/mail-client (servers and your app passwords for that mailbox), GET /v1/inbox/mail-client (servers only), GET /v1/inbox/app-passwords (?all=true for owners and admins: everyone's), POST /v1/inbox/app-passwords ({ "name", "mailboxIds" }, dashboard sessions only, returns password once), DELETE /v1/inbox/app-passwords/{id}, and POST /v1/inbox/mailboxes/{id}/mail-client/mobileconfig ({ "password"? }, returns the profile).

What the mail app sees

FolderContentsSpecial use
INBOXreceived mail in the Inbox view
Sentmail written from this address (dashboard, API, or a mail app)\Sent
Draftsdrafts of this address\Drafts
Archivethe Archive view\Archive
Junkthe Spam view\Junk
Trashthe Trash view\Trash
label namereceived mail with that label, outside Trash and Spam
  • Labels are folders. A label named Clients/Acme appears as Acme inside Clients. Creating, renaming or deleting a folder in the mail app creates, renames or deletes the label for the whole workspace. A label whose name clashes with a folder above (for example "Sent") appears as Labels/Sent.
  • Flags: \Seen is the shared read state and \Flagged is the star. \Answered, \Deleted and keywords (such as $Forwarded or Thunderbird tags) are kept for the mail app and not shown in the dashboard.
  • Moving and copying: a received message is in exactly one of INBOX, Archive, Junk and Trash, so copying it to one of them moves it. Copying to a label folder adds the label; moving from a label folder removes it. Received mail cannot be copied into Sent or Drafts.
  • Deleting: deleting in INBOX, Archive or Junk moves the message to Trash; deleting in Trash deletes it for good. Deleting in a label folder removes the label. Deleting a draft deletes it. Deleting in Sent takes the message out of Sent; the delivery record stays under Emails.
  • Drafts: a draft saved by a mail app appears in the dashboard (recipients, subject and text; attachments stay with the mail app's copy). A draft changed in the dashboard appears in the mail app as a new message.
  • Importing: messages a mail app uploads into INBOX, Archive, Junk, Trash or a label folder (for example when you drag mail over from another account) are stored as received mail. Inbox rules, forwarding and webhooks do not run for them, and they show no SPF or DKIM result.
  • Snooze and assignment have no IMAP equivalent: snoozed mail stays visible in INBOX.
  • Messages keep their UIDs (and each folder its UIDVALIDITY) across restarts, so mail apps do not download everything again.

Message source

Received mail keeps its original source (compressed, in the database), so the mail app gets exactly what was sent, including every header and attachment. Sources are removed after ONESEND_RETENTION_DAYS (default 90); after that, and for mail received before this feature, the message is rebuilt from what the inbox stores: headers, text, HTML and attachments up to 5 MB each. Mail sent from a mail app keeps the app's source; mail sent from the dashboard or the API is built from its stored parts.

Sending from a mail app

Mail apps send through the SMTP submission server (ONESEND_SMTP_PORT, default 2587; use 587 in production) with the same username and app password.

  • From must be the mailbox address the app password signed in with. Other senders are refused (550 5.7.1).
  • The message goes through your routing policy like any email (providers, suppressions, quotas), is threaded with the conversation it replies to, and appears in Sent in the dashboard and the mail app.
  • When the mail app also saves its own copy to Sent, OneSend recognises it by its Message-ID, so it is not listed twice.
  • In a sandboxed workspace messages are logged and not delivered, as for the API.

API keys keep working as SMTP passwords for applications; see SMTP.

Server configuration

VariableDefaultMeaning
ONESEND_IMAP_PORT1143Plain IMAP with STARTTLS. Use 143 in production. 0 or off turns it off.
ONESEND_IMAPS_PORT1993IMAP over TLS. Use 993 in production. Only opened with a certificate.
ONESEND_POP3_PORT1110Plain POP3 with STLS. Use 110 in production. 0 or off turns it off.
ONESEND_POP3S_PORT1995POP3 over TLS. Use 995 in production. Only opened with a certificate.
ONESEND_IMAP_TLS_KEY, ONESEND_IMAP_TLS_CERTthe SMTP certificatePEM files for IMAP and POP3. Without them, ONESEND_SMTP_TLS_KEY/CERT are used.
ONESEND_IMAP_ALLOW_INSECURE_AUTHfalseAccept passwords without TLS from any address. Without TLS, sign-in is otherwise only accepted from this machine (loopback). A TCP proxy on the same machine (HAProxy, stunnel) makes every client look local: terminate TLS in the proxy, or configure certificates here.
ONESEND_MAIL_HOSThost of ONESEND_PUBLIC_URLThe server name shown to users and in profiles, such as mail.acme.dev.
ONESEND_MAIL_PUBLIC_PORTSthe ports abovePorts shown to users when a proxy or NAT maps them, for example imaps=993,imap=143,pop3s=995,smtp=587.

Ports below 1024 need root or CAP_NET_BIND_SERVICE. A common setup keeps the defaults and maps the standard ports in Docker (-p 993:1993 -p 587:2587) with ONESEND_MAIL_PUBLIC_PORTS=imaps=993,smtp=587.

ONESEND_MAIL_HOST=mail.acme.dev
ONESEND_IMAP_TLS_KEY=/etc/letsencrypt/live/mail.acme.dev/privkey.pem
ONESEND_IMAP_TLS_CERT=/etc/letsencrypt/live/mail.acme.dev/fullchain.pem
ONESEND_SMTP_TLS_KEY=/etc/letsencrypt/live/mail.acme.dev/privkey.pem
ONESEND_SMTP_TLS_CERT=/etc/letsencrypt/live/mail.acme.dev/fullchain.pem

TLS certificates

Mail apps on phones and other computers need TLS: they send the password with every sign-in. Use a certificate for the mail host from a public CA, for example with certbot (certbot certonly --standalone -d mail.acme.dev), and point the variables above at it. The certificate is read at startup: restart after renewing it (a certbot deploy hook can do that). Self-signed certificates work for testing, but mail apps warn about them and some refuse them.

Firewall and DNS

  • Open the ports you use (for example 993, 587 and optionally 143, 995, 110) to the internet or your VPN.
  • Point the mail host at the server: mail.acme.dev A 203.0.113.10 (and AAAA).
  • Port 25 is the inbound MX receiver, not for mail apps; see Inbound mail options.

Autoconfig and DNS

Thunderbird and some other clients look up settings from the email address. OneSend serves Mozilla autoconfig XML at:

  • https://<server>/.well-known/autoconfig/mail/config-v1.1.xml?emailaddress=support@acme.dev
  • https://<server>/mail/config-v1.1.xml

To use it for a domain, add (all optional):

RecordValueUsed by
autoconfig.acme.dev CNAMEyour OneSend host (it must serve HTTPS for that name)Thunderbird
_imaps._tcp.acme.dev SRV0 1 993 mail.acme.dev.RFC 6186 clients
_imap._tcp.acme.dev SRV0 1 143 mail.acme.dev.RFC 6186 clients
_pop3s._tcp.acme.dev SRV0 1 995 mail.acme.dev.RFC 6186 clients
_submission._tcp.acme.dev SRV0 1 587 mail.acme.dev.RFC 6186 clients

Outlook's Autodiscover is not provided; enter the servers by hand in Outlook.

Protocol support

  • IMAP4rev1 (RFC 3501) with LITERAL+, SASL-IR, ID, ENABLE, IDLE, NAMESPACE, UNSELECT, UIDPLUS (APPENDUID, COPYUID, UID EXPUNGE), MOVE, SPECIAL-USE and CHILDREN. Sign-in with LOGIN or AUTHENTICATE PLAIN. FETCH supports FLAGS, UID, INTERNALDATE, RFC822.SIZE, ENVELOPE, BODY, BODYSTRUCTURE, RFC822, RFC822.HEADER, RFC822.TEXT and BODY[…] / BODY.PEEK[…] with HEADER, HEADER.FIELDS, HEADER.FIELDS.NOT, TEXT, MIME, part numbers and partial ranges. SEARCH supports all RFC 3501 keys (charset UTF-8 or US-ASCII); RECENT and NEW match nothing (\Recent is not tracked).
  • IDLE: new mail and changes from the dashboard are reported within a second; changes made by another server process sharing the database within 30 seconds.
  • POP3 (RFC 1939) with CAPA, STLS, UIDL, TOP, USER/PASS and AUTH PLAIN. The maildrop is INBOX. UIDL values are stable. DELE moves messages to Trash when the session ends with QUIT. Downloading with POP3 does not mark mail read for the team.
  • Not supported: CONDSTORE/QRESYNC, LIST-EXTENDED and ESEARCH (clients fall back), COMPRESS, NOTIFY, METADATA, ACLs and shared folders (each mailbox signs in on its own), Sieve, Outlook Autodiscover.

Limits

  • Messages uploaded by a mail app (APPEND): 25 MB. Sending: 25 MB.
  • 50 connections per IP address for IMAP and 20 for POP3; 1,000 IMAP connections per server.
  • 50 active app passwords per member.
  • Idle connections are closed after 30 minutes (IMAP, as RFC 3501 allows) or 10 minutes (POP3). Mail apps reconnect on their own.
  • Every folder listing is read from the inbox when a mail app checks for mail; very large folders (100,000+ messages) are slower to open the first time.

Troubleshooting

  • "Invalid credentials": use the full mailbox address as the username and an app password, not your account password. Check that the app password was not revoked and that it opens this mailbox.
  • "Sign in over TLS" / PRIVACYREQUIRED / LOGINDISABLED: configure a certificate and use port 993 (or 143 with STARTTLS). Plain-text sign-in is only accepted from the server itself.
  • The mail app cannot connect: check that the port is open (openssl s_client -connect mail.acme.dev:993), that ONESEND_MAIL_HOST resolves to the server, and the server log line Mail client access: IMAP :….
  • Sending fails with From must be …: the mail app account's email address must be the mailbox address.