Docs »

Setup »

Mail »

Mailboxes

This page configures the mailboxes that will be checked for new mail.

It is highly recommended that you configure a single mailbox as a "dropbox". You can redirect mail to a single mailbox even if you have dozens of email addresses.

For example, you can redirect sales@example.com and support@example.com to cerb@example.com.

Your mail routing and filtering rules will still be able to identify the original destination. This is much more efficient than checking several mailboxes every few minutes.

If you're using Cerb Cloud, you can alternatively redirect your incoming mail to support@<you>.cerb.email for instant delivery. Replace <you> with the name of your instance. With this delivery method you won't need to set up a mailbox here.

Adding a mailbox

To add a new mailbox, click the (+) icon in the blue bar of the worklist.

The editor has ten fields, in this order:

  • Enabled

    If this toggle is on then new mail will be downloaded from this mailbox. Otherwise, this mailbox will not be checked until it is re-enabled.

  • Name

    A friendly name to use for this mailbox when it is displayed in the interface.

  • Protocol

    The protocol to use when connecting to this mailbox. Choose POP31 or IMAP, each offered as STARTTLS, TLS/SSL, or Unencrypted – the option labels carry the encryption state, so the selected value reads like IMAP (Unencrypted). Use an encrypted option unless you have a good reason to do otherwise.

    If you aren't using an encrypted protocol then your password will be sent in cleartext. This might be a security issue depending on the network between your web server and mail server. Encrypt whenever possible.

  • Port

    The network port2 to connect to on the mail server. If this field is left blank then the standard ports will be used by default. If your mail server uses a non-standard port then you will need to enter that number here.

  • Host

    The mail server to connect to, e.g. imap.gmail.com or outlook.office365.com.

  • User

    The username used to authenticate access to this mailbox. Depending on your mail server, this may be a simple username (e.g. support) or an email address (e.g. support@example.com). If you aren't sure, ask your system administrator.

  • Password

    The password used to authenticate access to this mailbox. Leave it blank when authenticating with XOAuth2.

  • XOAuth2 (optional)

    A chooser for the connected account to authenticate with, instead of a password – you pick an existing account rather than pasting a token. Leave it empty for password authentication. See below.

  • Timeout

    The socket timeout, in seconds, when downloading mail.

  • Max Message Size

    The largest message to download, in kilobytes. 0 disables the limit.

Below the fields are three buttons – Save Changes, Test, and Delete. Deleting a mailbox will not affect any previously downloaded mail.

Messages in a mailbox are deleted once downloaded (unless the mail server prevents it, as Google Workspace does). If that isn't desirable, create a disposable mailbox to use instead and have copies of your incoming mail sent to it.

Authenticating with OAuth2

Major providers have retired passwords for mail access. Google no longer accepts one for Gmail over POP3 or IMAP, and Microsoft has been retiring them for Microsoft 365. Both use XOAUTH2 instead, which authenticates with a rotating, time-limited access token rather than a stored password.

Cerb has supported XOAUTH2 for IMAP mailboxes since 9.6 and for POP3 mailboxes since 11.1.1.

Setting one up is three records, in this order:

  1. A connected service holding the provider's OAuth2 endpoints and your application's credentials.
  2. A connected account that authenticates against that service. This is the record that holds the tokens, and it is shared – one account can serve a mailbox, an automation, and a transport.
  3. The mailbox itself, with that connected account chosen in its XOAuth2 field and its Password left blank.

Then use Test to confirm the token works before saving.

Add the connected service from the library rather than building it by hand. A library package fills in the authorize and token URLs and prefills the scopes, including the offline_access scope that lets Cerb refresh an expiring token on its own. Cerb 12.0 added a Microsoft Entra ID package covering SMTP, POP3, and IMAP for Microsoft 365; you supply the client ID, client secret, and directory ID from your app registration.

For worked examples end to end, see Authenticate a Gmail mailbox using IMAP or POP3 with XOAUTH2 and Authenticate an Office365 mailbox using XOAUTH2. For Gmail, Gmail covers creating the connected account those steps start from.

The library's Google service ships without a mail scope. It's scoped for calendar and profile access, which is what it was built for. Gmail over IMAP with XOAUTH2 also needs https://mail.google.com/, so add it to the service's scopes yourself -- nothing will prompt you, and the connected account will authorize successfully and then fail to read mail. The Microsoft Entra ID package doesn't have this problem; its scopes are prefilled for mail.

Microsoft 365 uses outlook.office365.com on port 993 for IMAP, and smtp.office365.com on port 587 with TLS for the matching transport. Both leave their passwords blank and select the same connected account.

Testing a mailbox

You can verify your mailbox connection details by clicking the Test button.

References

  1. Wikipedia: Post Office Protocol (POP3) - https://en.wikipedia.org/wiki/Post_Office_Protocol ↩

  2. Wikipedia: Port (computer networking) - https://en.wikipedia.org/wiki/Port_(computer_networking) ↩