Permissions
Every key carries a list of what it may do, one permission per operation. Start from a preset, or choose them one by one.
Permissions only take away. A key can never do more than its owner, so what it can do is what they can do and it was allowed, both at once.
Presets
- Read only
- Dashboards and reporting. It can’t change or send anything.
- Read and send
- A client, a contact form, an integration that answers mail. It can’t touch mailbox settings.
- Full access
- Everything its owner can do, including deleting mailboxes.
Keep Full access for software that needs it
Only Full access can delete a mailbox, and with it all its mail. It’s the difference between a leaked key that reads mail and one that deletes it.
Conversations
threads:listEvery preset- List conversations, and search. Needed for List threads.
threads:readEvery preset- Read one conversation and its messages. Needed for Get a thread and List a thread’s labels.
threads:updateRead and send, Full access- Change status, important, read and assignment. Needed for Update a thread and Update many threads.
messages:readEvery preset- Read a single message, and how a send went. Needed for Get a message.
threads:moveRead and send, Full access- Move a conversation to another mailbox. Needed for Update a thread.
sync:readEvery preset- Follow what changed since the last call. Needed for Follow changes.
Labels
labels:listEvery preset- List labels. Needed for List labels and Get a label.
labels:createFull access- Create a label. Needed for Create a label.
labels:updateFull access- Rename or recolour a label, or change where it can be used. Needed for Update a label.
labels:deleteFull access- Delete a label. Needed for Delete a label.
threads:labelRead and send, Full access- Add or remove a label on a conversation. Needed for Label a thread.
Writing and sending
drafts:listEvery preset- List drafts. Needed for List drafts.
drafts:readEvery preset- Read a draft. Needed for Get a draft.
drafts:createRead and send, Full access- Start a draft. Needed for Create a draft.
drafts:updateRead and send, Full access- Edit a draft. Needed for Update a draft.
drafts:deleteRead and send, Full access- Discard a draft, or cancel a send. Needed for Delete a draft.
messages:replyRead and send, Full access- Start a reply or forward. Needed for Reply or forward.
drafts:sendRead and send, Full access- Send. Needed for Send a draft.
scheduled:listEvery preset- List scheduled sends. Needed for List scheduled messages.
messages:rescheduleRead and send, Full access- Move or hurry a scheduled send. Needed for Reschedule a message.
Attachments
attachments:readEvery preset- Download a file. Needed for Download an attachment.
attachments:listEvery preset- List the files on a draft. Needed for List a draft’s attachments.
attachments:createRead and send, Full access- Attach a file. Needed for Upload an attachment.
attachments:confirmRead and send, Full access- Confirm an upload finished. Needed for Confirm an upload.
attachments:deleteRead and send, Full access- Remove a file from a draft. Needed for Remove an attachment.
Shared text and people
contacts:readEvery preset- Read contacts and their fields. Needed for List contacts, Get a contact and List contact fields.
contacts:writeFull access- Add, change and delete contacts. Needed for Create a contact, Update a contact, Update a contact by email, Bulk update contacts and Delete a contact.
contacts:listEvery preset- Look up people from mail. Needed for List correspondents.
signatures:readEvery preset- Read signatures. Needed for Get signatures.
signatures:writeFull access- Write a signature. Needed for Set your signature.
templates:listEvery preset- List saved replies. Needed for List saved replies.
templates:createFull access- Create a saved reply. Needed for Create a saved reply.
templates:updateFull access- Edit a saved reply. Needed for Update a saved reply.
templates:deleteFull access- Delete a saved reply. Needed for Delete a saved reply.
Mailboxes
mailboxes:listEvery preset- List mailboxes. Needed for List mailboxes.
mailboxes:readFull access- Read connection settings. Needed for Get a mailbox.
mailboxes:createFull access- Connect a mailbox. Needed for Add a mailbox.
mailboxes:updateFull access- Reconfigure or pause a mailbox. Needed for Update a mailbox.
mailboxes:deleteFull access- Delete a mailbox and all its mail. Needed for Delete a mailbox.
imports:listFull access- Watch history imports. Needed for List imports.
imports:startFull access- Start a history import. Needed for Import history.
imports:stopFull access- Stop a history import. Needed for Stop an import.
Teams
teams:listFull access- List teams, their people and mailboxes. Needed for List teams and Get a team.
teams:createFull access- Create a team. Needed for Create a team.
teams:updateFull access- Rename a team, or change who is in it. Needed for Update a team, Add a team member and Remove a team member.
teams:deleteFull access- Delete a team. Needed for Delete a team.
Webhooks
webhooks:listFull access- List this key’s webhooks and their deliveries. Needed for Manage webhooks.
webhooks:manageFull access- Add, change, test and delete this key’s webhooks. Needed for Manage webhooks.
contacts:write comes only with contacts:read, since software that keeps contacts in step reads them first. A key reaches its owner’s personal contacts only when it was made with “Include my personal contacts”, which only its owner can turn on.
A missing permission
Calling an endpoint without its permission is 403 missing_scope. The message names the permission, and so does the X-Required-Scope header, so you don’t have to look it up.
Some permissions do nothing alone: a draft has to exist before it can be sent, so drafts:send wants drafts:create or messages:reply beside it. DMU Mail points these out when you create a key but allows them, because a key that only sends drafts something else wrote can be exactly what you want.