Authentication & access
Understand your organization, API key, and permissions.
Every authenticated request uses the API key supplied during onboarding:
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.
Key issuance, rotation, revocation, permission changes, and organization policy changes currently go through the Mailactor team. Contact us with the operation and request ID; do not include your secret.