Add a mailbox

POST/mailboxes

Connects an address your organisation already has, so a script can add mailboxes without anyone opening DMU Mail.

Needs the permissionmailboxes:create

The password is encrypted with your organisation’s key and no endpoint ever returns it. A wrong password doesn’t fail here: the first sync fails and marks the mailbox broken, so check List mailboxes afterwards.

New mail arrives by itself from then on. To bring older mail across, start an import.

Body

emailstringrequired: The address.
passwordstringrequired: Its password, or an app password if the provider uses them.
imapHoststringrequired: The incoming mail server.
smtpHoststringrequired: The outgoing mail server.
displayNamestringoptional: The name recipients see. Defaults to the address.
imapPortnumberoptional: Defaults to 993.
smtpPortnumberoptional: Defaults to 587.
smtpEncryptionstringoptional: tls, ssl or none. Defaults to tls.
imapUsernamestringoptional: Defaults to the address, as does smtpUsername.
accessobjectoptional: Who can see a shared mailbox: { "everyone": true }, or { "everyone": false, "teamIds": […], "userIds": […] } for the teams and people ticked on it. Leave it out for everyone. Administrators always see it.
teamIdstringoptional: The older form of access: exactly one team. Used only when access isn’t sent.
ownerUserIdstringoptional: Leave it out for a shared mailbox. For one private to the key’s owner, their own user id; anyone else’s is refused.

Returns

idstring: The new mailbox.

Errors

400invalid_mailbox: A setting is missing or wrong, and the message says which. A server on a private network is refused too.
400invalid_access: access isn’t { everyone, teamIds, userIds }, or an id in it isn’t one.
400unknown_team: A team in teamIds isn’t in the organisation.
400unknown_person: Someone in userIds isn’t an active member of the organisation.
401invalid_key: The key is wrong, expired or revoked. With no Authorization header at all, the code is missing_credentials.
403missing_scope: The key doesn’t have mailboxes:create. The X-Required-Scope header names what’s missing.
409mailbox_exists: That address is already connected.
409plan_limit: The plan’s mailboxes are all in use.
429rate_limited: More than 120 requests a minute from this key. Wait for Retry-After seconds.