Authentication
Every request carries an API key in its Authorization header. A key acts as the administrator who created it, in one organisation.
Create a key
An administrator creates keys in DMU Mail, under Settings, API keys. Name the key after what will use it, choose what it may do (see Permissions) and copy it.
It’s shown once. Only a hash of it is stored, so nobody, us included, can show it to you again. If it’s lost, revoke it and create another.
Send it
Header
Authorization: Bearer dmk_7f3a9c2e1b4d_Xq8v…Only this header is read: never a cookie, never the query string. Keys start with dmk_ so that secret scanners can spot one that has leaked into a public repository.
What a key can reach
A key acts as the person who created it, its owner. It reaches exactly the mailboxes they can: those shared with everyone, with one of their teams or with them, and their private ones. Permissions can narrow what a key does, but nothing lets it see more than its owner.
If the owner is suspended or removed from the organisation, every key they created stops working at once. A key belongs to the one organisation it was created in, and nothing in a request can make it answer for another.
What a key changes is recorded under the key’s name, so a colleague reading a conversation sees which integration closed it.
Conversations given to the owner by a mention or an assignment can be listed and read like any other, but their mailbox isn’t listed and they can’t be moved to spam or trash.
Your organisation’s sign-in rules, such as two-step verification, don’t apply to keys. A key isn’t a sign-in.
When it’s refused
Errors
401missing_credentials- There’s no Authorization header, or it doesn’t start with
Bearer. 401invalid_key- The key is unknown, revoked or expired. It’s one answer for all three, on purpose.
403missing_scope- The key doesn’t have the permission. The message and the
X-Required-Scopeheader name it. 403plan_no_api- The organisation is on the Individual plan, which has no API. Its keys work again once it moves to a team plan.
423organisation_deleting- The organisation is waiting to be deleted. Cancelling the deletion makes its keys work again.