Authentication & access
Understand your organization, API key, and permissions.
After your access is approved, create an agent key in Dashboard → API keys. Save its one-time secret in your local secret manager or environment. Dashboard keys expire after 30 days and grant inbox, message, domain, webhook, and delivery-read access.
Every authenticated API request uses that key:
curl --fail-with-body --silent --show-error \
https://api.mailactor.com/v1/me \
-H "x-api-key: $MAILACTOR_API_KEY"An organization ID alone does not grant access. Your key identifies your organization, and resource IDs must belong to it. Keep credentials on your backend or in your agent's secret store. Never put keys in URLs, browser bundles, email bodies, or logs.
Inspect what your key can do
GET /v1/me is available to every valid tenant key without an additional scope.
| Response field | What to check |
|---|---|
organization.status | Your organization must be active. |
organization.sendLimits | Effective per-minute and daily sending limits. |
apiKey.scopes | Permissions granted to this key. |
apiKey.inboxIds | Any restriction to particular inboxes. |
apiKey.allowedIps | Exact caller IP restrictions, when configured. |
apiKey.sendMode | Whether the key can start new conversations or only reply. |
apiKey.allowedRecipientDomains | Any restriction on recipient domains. |
apiKey.expiresAt | The key's expiration. |
managedStarter | Your lifetime managed-domain allowance: limit, used, remaining. |
platformLimits | Recipient, content-byte, inbox, domain, and webhook caps. |
Permissions by task
| Scope | Tasks |
|---|---|
mailbox:manage | Create and delete inboxes; delete messages. |
mailbox:read | List inboxes, read threads, export messages, and access permitted attachments. |
mailbox:send | Send from an inbox and reply to a thread. |
delivery:read | Inspect submission status, events, metrics, suppressions, and complaints. |
delivery:send | Use the lower-level send endpoint and manage suppressions. |
domain:manage | Register, inspect, and verify customer domains. |
webhook:manage | Create, list, and delete webhook endpoints. |
validation:use | Validate email addresses. |
* grants all tenant scopes, but other key restrictions still apply. A scope does not bypass recipient policy, inbox restrictions, verified-domain requirements, or traffic limits.
When to contact us
A 401 means the key cannot authenticate from this caller: check the secret, expiry, revocation, and allowed source IPs. A 403 means an authenticated action is blocked by permissions or policy.
You can create and revoke agent keys in the dashboard. To rotate a working key, create one with a new name, update your agent's secret manager, confirm access, then revoke the old key. If a creation response is lost, refresh the key list and revoke that named key before creating its replacement; the secret cannot be retrieved again.
For different permissions or organization policies, contact us with the operation and request ID. Do not include your secret.