Scopes
A scope is one permission the user grants your app. Request only what your features use: fewer scopes means a shorter consent screen and more users who click Allow.
All scopes
| Scope | Endpoints | What the user sees on the consent screen |
|---|---|---|
verify:single | POST /v1/verify | Verify individual email addresses using your credits |
verify:bulk | POST /v1/verify/bulk, file uploads and previews | Start bulk verification jobs using your credits |
jobs:read | GET /v1/jobs, GET /v1/jobs/{id}, /results, /download | See your bulk jobs and download their results |
jobs:write | DELETE /v1/jobs/{id} (cancel) | Cancel your bulk jobs |
webhooks:manage | All /v1/webhooks endpoints | Create, change and delete webhooks on your account |
credits:read | GET /v1/credits | See your credit balance and usage |
monitors:read | GET /v1/monitors, GET /v1/monitors/{id}, /runs | See your deliverability monitors and their results |
monitors:write | POST, PATCH, DELETE /v1/monitors, POST .../run | Create, change, delete and run deliverability monitors |
account:read | GET /v1/me | See your name, email address, account type and credit balance |
OAuth apps cannot request the * scope. It exists only for API keys. Domain tools under /v1/tools follow the same rules as for API keys; see Domain Tools.
Requesting scopes
- Send scopes space separated in the
scopeparameter of the authorize URL:scope=verify:bulk%20jobs:read%20account:read. - The token response has a
scopefield with what was granted. Store it with the tokens and check it before you call an endpoint. - A call without the right scope returns
403with error codeinsufficient_scope. - To add a scope later, send the user through the authorize URL again with the full new list. The consent screen shows only the new permissions. The new grant replaces the old one.
Least privilege
Ask for what you use today
If your app only verifies signups one at a time, request verify:single and nothing else. Add verify:bulk and jobs:read the day you ship list imports, not before.
Add account:read for a better connected state
account:read lets you show "Connected as jane@acme.com, 12,400 credits" and warn before a job runs out of credits. It is low risk and users expect it.
Write scopes get extra review
webhooks:manage, jobs:write and monitors:write change things in the user's account. Reviewers will ask what feature uses them. Unused write scopes are the most common reason a review is sent back.
Common sets
| App type | Scopes |
|---|---|
| Signup form or CRM that checks one address at a time | verify:single account:read |
| List cleaning or import feature | verify:bulk jobs:read account:read |
| Reporting dashboard | credits:read jobs:read monitors:read |
| AI agent or MCP client | verify:single verify:bulk jobs:read jobs:write credits:read |