Skip to main content
Inbound presents received email through a managed IMAP mailbox rather than a conventional standalone mail store. INBOX, Junk and scope folders are views of the mail Inbound has received, so some operations behave differently than on a traditional IMAP server.

​
Default folders

Each mailbox credential includes these folders: The personal namespace is "" and the hierarchy separator is /. INBOX and the special-use folders cannot be deleted or renamed. With a read_write credential you can create, rename, and delete other folders. Renaming a folder also renames its subfolders; deleting a folder keeps its subfolders. Creating or renaming onto an existing custom folder returns NO [ALREADYEXISTS], and onto a special-use or Scopes/... name returns NO [CANNOT]. Read-only credentials can’t change folders or subscriptions. Folders, flags, and appended messages belong to one credential. Other credentials on the same account don’t see them.

​
Scope folders

Every configured scope also appears as a folder under Scopes:
Scopes is a non-selectable container (\Noselect), and its name is reserved. A domain scope appears as Scopes/*@example.com; an address scope appears as Scopes/support@example.com. Scope folders are filtered views of the same messages as INBOX (junk mail appears only in Junk). They always open read-only, even for read_write credentials. You cannot append, move, or copy messages into a scope folder, change flags in it, or expunge from it. A read_write credential can copy messages from a scope folder into a writable folder.

​
Capabilities

Before login, the server advertises exactly these capabilities:
After login, AUTH=PLAIN and SASL-IR are no longer listed. Supported commands:
  • Authentication: LOGIN and AUTHENTICATE PLAIN (with SASL-IR). A PLAIN authorization identity different from the login email is rejected with NO [AUTHORIZATIONFAILED].
  • Folders: LIST, LSUB, NAMESPACE, SELECT, EXAMINE, STATUS, CREATE, RENAME, DELETE, SUBSCRIBE, UNSUBSCRIBE.
  • Messages: FETCH, SEARCH, STORE, COPY, MOVE, and their UID forms, plus EXPUNGE, UID EXPUNGE, APPEND, CLOSE, UNSELECT, CHECK, NOOP, and IDLE.
  • ENABLE UTF8=ACCEPT, before a folder is selected. Other ENABLE arguments are ignored.
COPY and APPEND return COPYUID and APPENDUID. MOVE returns COPYUID followed by an untagged EXPUNGE for every moved message, and moving a message into the folder it’s already in returns NO [CANNOT]. EXPUNGE and UID EXPUNGE send an untagged EXPUNGE for each removed message. SUBSCRIBE and UNSUBSCRIBE persist per credential; LSUB returns subscribed folders. Extensions that aren’t advertised are not supported, including STARTTLS (use implicit TLS on port 993), CONDSTORE, QRESYNC, QUOTA, COMPRESS=DEFLATE, SORT, THREAD, ACL, OAuth (XOAUTH2 or OAUTHBEARER), and the Gmail-only XLIST. Requests that would enable CONDSTORE, such as SELECT (CONDSTORE) or SEARCH MODSEQ, are rejected with BAD. SEARCH supports sequence sets, UID, flag and keyword keys (such as SEEN, UNSEEN, DELETED, FLAGGED, KEYWORD), BEFORE/ON/SINCE, SENTBEFORE/SENTON/SENTSINCE, LARGER/SMALLER, OLDER/YOUNGER (WITHIN), HEADER, FROM, TO, CC, BCC, SUBJECT, BODY, TEXT, OR, and NOT.
  • Text searches are case-insensitive substring matches. For received mail they match Inbound’s parsed fields: SUBJECT, the address headers, and the plain-text body. TEXT checks the subject and plain-text body, so text that exists only in an HTML part may not match. For appended messages they match the raw message.
  • HEADER searches on other header names match the raw message.
  • SENTBEFORE, SENTON, and SENTSINCE use the parsed Date header of received mail and don’t match appended messages. BEFORE, ON, SINCE, OLDER, and YOUNGER use the internal date, which is when Inbound received the message.
  • \Recent is never set, so RECENT and NEW match nothing.
  • Unknown search keys are rejected with BAD Unknown search term. A CHARSET argument is accepted and ignored. Dates are compared in UTC.

​
New-message notifications

During IDLE, the server sends EXISTS as soon as new mail is synchronized into the selected folder, including mail addressed to a secondary envelope recipient. Outside IDLE, new messages are reported on the next command, such as NOOP. Active sessions are also refreshed about every 60 seconds as a fallback. An IDLE command ends after 30 minutes: the server sends * BYE IDLE terminated and closes the connection. Reissue IDLE before then (most clients restart it every 29 minutes) or reconnect automatically.

​
Flags and read state

Writable credentials can set standard flags (\Seen, \Answered, \Flagged, \Deleted, \Draft) and keywords in writable folders. Fetching message content from a writable folder sets \Seen unless the client uses BODY.PEEK. Read-only credentials, EXAMINE, and scope folders never set \Seen. STORE without .SILENT returns the updated flags. Flags set on a received message in INBOX also apply to the same message in the credential’s scope folders. Flags on copies in other folders, such as a custom folder, are independent.
IMAP flags and the mailbox HTTP API share the same state. They are separate from the dashboard’s read state: marking a message read in a mailbox does not mark it read in the dashboard, and the reverse is also true.

​
Known limitations

​
Cross-session updates and retained history

New messages, expunges and moves are pushed to other open sessions on the same folder as EXISTS and EXPUNGE. Flag changes arrive as FETCH FLAGS, including changes made through HTTP. The update journal is stored in Postgres rather than in a gateway process, so it survives restarts. Expunge history is retained for approximately seven days; a session behind the retained history is disconnected and must reconnect and resynchronize rather than silently miss removals.

​
First sync of a large mailbox

Each sync adds at most 500 received messages that this credential hasn’t seen yet, newest first, so new arrivals don’t wait behind older mail. On a mailbox with a lot of existing mail, INBOX fills in over the next few syncs, and older messages can get higher UIDs than newer ones.

​
Received-message deletion and moves

EXPUNGE and MOVE do not delete the underlying received email. Expunging or moving a received message out of INBOX removes it from INBOX and every scope folder of that credential, and it stays removed there. It remains available through the API and dashboard, and in other credentials. Copying or moving it back into INBOX restores it. Don’t use IMAP deletion as permanent deletion.
Moving a received message into a custom folder or Trash does create a copy there that stays until you expunge it. Moving it into Junk marks it as junk instead (see Junk). Messages created with APPEND, such as sent copies and drafts, are stored separately and are permanently removed when their last copy is expunged.

​
Sent mail

Immediate sending through SMTP or the HTTP API with a read_write mailbox password saves a message in that credential’s Sent in the background. Clients may still save their own copy with APPEND: a matching Message-ID already in Sent is deduplicated, in either order. Account-key sends also save to enabled read/write mailboxes whose sending address (or login email, when no sending address is set) exactly matches the From address; domain scopes alone do not select a mailbox. SMTP-only credentials and scheduled sends do not populate a mailbox. Historical sent email records are not backfilled.
SMTP accepts messages up to 3 MiB, but client APPEND accepts at most 1 MiB. Automatic sent copies count toward the account’s appended-storage quota. A sent-copy failure does not undo an accepted delivery or cause it to be retried.

​
Junk

The junk filter decides whether a received message belongs in INBOX or in Junk; it is never in both. Each credential can have its own spam level and sender lists. Moving a received message from INBOX into Junk marks it as junk, and moving it from Junk back to INBOX marks it as not junk. The decision applies to this credential only, in IMAP and the mailbox API; it doesn’t change other credentials, the account verdict or webhooks. Copying a received message into INBOX or Junk has the same effect. New mail appears in INBOX or Junk once the junk filter has made its verdict, normally within a few seconds of arrival (at most about two minutes if filtering is unavailable). If the verdict that applies to this credential changes later, for example when the account verdict changes in the email API or dashboard and the credential has no decision of its own, the message moves between INBOX and Junk with its flags, and open sessions receive EXPUNGE for the folder it left and EXISTS for the folder it entered. Expunging a received message from Junk removes it from the credential’s folders; it doesn’t return to INBOX if it is later marked as not junk. Messages appended to Junk are stored like other appended messages.

​
Filters

Mailbox filters run once, when a received message first enters the credential’s mailbox, and can move it to another folder, flag it or mark it as junk. A message a filter moved out of INBOX is no longer in INBOX or the scope folders, like any other move. Changing filters later doesn’t re-sort existing mail.

​
Guard-filtered messages

Messages blocked by Guard are not synchronized, and their content cannot be fetched. If a message is blocked after it was already synchronized, it is removed from the credential’s folders at the next sync: right away for open sessions, otherwise when the client opens the folder or requests its STATUS. Email clients may still show content they cached earlier.

​
Scope changes and revoked access

When a credential’s scopes, login email, type, access mode, sender settings, enabled state, password, protocols, allowedIps or selfService change, its active IMAP sessions immediately receive * BYE Mailbox credentials or scopes changed and must reconnect. Changing its name, storageQuotaBytes, dailySendLimit, spam settings or filters doesn’t end sessions. On the next folder listing or selection, folders for removed scopes disappear, and received messages that no longer match any remaining scope are removed from all of the credential’s folders. Appended messages are not affected. Each login rechecks that the login email’s domain is verified, that at least one scope domain is verified, and that an exact sender identity is still covered by a verified scope. It also checks that the credential’s protocols.imap is enabled and that the client address is in its allowedIps (see Access and Limits). If not, authentication fails with the same NO [AUTHENTICATIONFAILED] as a wrong password. Open sessions repeat these checks about every 5 minutes. A session whose login email domain is no longer verified receives * BYE Mailbox credentials are no longer valid; one that lost a verified scope domain receives * BYE Mailbox credentials or scopes changed. Every session must log in again after 24 hours (* BYE Session expired, please log in again). To end access right away, disable the credential, rotate its password, or delete it.

​
Message and storage limits

An APPEND over 1 MiB is rejected with NO [TOOBIG]. Appended messages must be valid UTF-8 without NUL bytes; encode other 8-bit content with base64 or quoted-printable. The account storage and message-count limits are shared by all of the account’s credentials and folders. A credential’s own storage quota counts each message it stored once, however many folders hold it. Exceeding either limit returns NO [OVERQUOTA]. For SMTP limits, see Send with SMTP.

​
Connection limits and timeouts

Connections over the per-IP limit are closed without a reply. A connection that hasn’t logged in within 30 seconds receives * BYE Authentication timeout, closing connection. Once a login is throttled, attempts return NO [AUTHENTICATIONFAILED] until the window ends, even with the correct password. Authentication requests are also rate-limited by the API, so avoid reconnect loops and retry with backoff.

​
Troubleshooting

Scopes and Permissions

Understand exact domain matching, sender policies, and read-only scope views.

Manage Credentials

Change access levels, replace scopes, rotate passwords, and disable credentials.