API Error Codes

No Authorization header was provided, or the API key does not match any active key in the system.

Fix: Include Authorization: Bearer mm_live_... in your request header. Verify the key has not been revoked.

The request was made to an authenticated endpoint without any Authorization header.

Fix: Add Authorization: Bearer mm_live_YOUR_KEY to your request.

The API key format is correct but the key does not exist or has been revoked.

Fix: Generate a new API key via POST /v1/api-keys or check your existing keys with GET /v1/api-keys.

A webhook endpoint received a request with invalid or missing HTTP Basic Auth credentials.

Fix: This is an internal webhook authentication error. Ensure the webhook secret is correctly configured.

A Stripe webhook was received without the required stripe-signature header.

Fix: This is an infrastructure error. Ensure Stripe webhook signing is configured correctly.

The API key does not have the admin scope required for this operation (creating mailboxes, managing API keys, billing, etc.).

Fix: Use an API key with admin scope, or create a new one: POST /v1/api-keys with {"scopes": ["admin"]}.

The API key does not have the read scope required for listing or reading emails, mailboxes, or contacts.

Fix: Use an API key with read scope. The admin scope includes read access.

The API key does not have the send scope required for sending emails, replying, cancelling, or tagging.

Fix: Use an API key with send scope.

The API key does not have the oversight scope required for approving or rejecting emails.

Fix: Use an API key with oversight scope.

The API key does not have the oversight or oversight_read scope required for listing pending emails.

Fix: Use an API key with oversight_read (read-only) or oversight (read + decide) scope.

The account associated with this API key has been deactivated (enforcement action, unpaid subscription, or pending confirmation).

Fix: Check your oversight email for enforcement notices. Contact [email protected] for reactivation.

The to array in the send request is empty or missing.

Fix: Include at least one email address in the to field.

The subject field is missing from the send request.

Fix: Include a subject string in your request body.

The markdown field is missing from the send or reply request.

Fix: Include a markdown string with the email body content.

The local part of the mailbox address contains invalid characters.

Fix: Use only lowercase letters, numbers, dots, underscores, and hyphens. Must start and end with alphanumeric.

The oversight_mode value is not a recognized mode.

Fix: Use one of: read_only, gated_all, gated_send, monitored, autonomous.

Account signup is missing the required operator email address.

Fix: Provide a valid oversight_email for human oversight notifications.

The email address provided does not match basic email format validation.

Fix: Provide a properly formatted email address (e.g., [email protected]).

Account signup is missing the operator/organization name.

Fix: Include operator_name in your signup request.

Signup request has accepted_tos or accepted_operator_agreement set to false.

Fix: Set both accepted_tos and accepted_operator_agreement to true.

Signup request has accepted_anti_spam_policy set to false.

Fix: Set accepted_anti_spam_policy to true. MultiMail only supports transactional email.

The slug provided or derived from the operator name does not meet format requirements.

Fix: Use a slug with at least 2 characters, starting and ending with alphanumeric characters.

The oversight decide request is missing email_id or action.

Fix: Include both email_id and action (either "approve" or "reject").

Contact creation is missing required fields.

Fix: Include both name and email in the request body.

An attachment in the send/reply request is missing required fields.

Fix: Every attachment must include name, content_base64, and content_type.

The combined size of all attachments exceeds the 10 MB maximum.

Fix: Reduce attachment sizes or send fewer attachments per email.

The status query parameter is not a recognized email status.

Fix: Use one of: unread, read, archived, deleted, pending_send_approval, pending_inbound_approval, rejected, cancelled, send_failed.

An API key scope value is not recognized.

Fix: Valid scopes are: read, send, admin, oversight, oversight_read.

A webhook URL was provided without HTTPS.

Fix: All webhook URLs must start with https://.

The recipient has previously bounced or unsubscribed and is on the suppression list.

Fix: Check the suppression list with GET /v1/suppression. Remove non-bounce suppressions with DELETE /v1/suppression/{address}.

The email content was flagged by the outbound content filter (phishing patterns, prohibited MIME types, etc.).

Fix: Review the error message for the specific reason. See the acceptable use policy.

The webhook event type is not recognized.

Fix: Valid event types: message.received, message.sent, message.delivered, message.bounced, message.complained, oversight.pending, oversight.approved, oversight.rejected.

The domain name provided does not match the expected format.

Fix: Use a valid domain name (e.g., mail.example.com).

The mailbox ID does not exist, has been deleted, or belongs to a different tenant.

Fix: List your mailboxes with GET /v1/mailboxes to find valid IDs.

The email ID does not exist in the specified mailbox.

Fix: List emails with GET /v1/mailboxes/{id}/emails to find valid IDs.

The email you are trying to reply to does not exist in the specified mailbox.

Fix: Verify the email ID and mailbox ID. The original email may have been deleted.

No emails exist with the specified thread ID in this mailbox.

Fix: Thread IDs are returned in email responses. Use a valid thread_id from a previous email.

The email specified for oversight decision is not in a pending state, or does not exist.

Fix: List pending emails with GET /v1/oversight/pending before deciding.

The contact ID does not exist or belongs to a different tenant.

Fix: Search contacts with GET /v1/contacts to find valid IDs.

The attachment filename does not exist on the specified email.

Fix: Read the email first with GET /v1/mailboxes/{id}/emails/{id} to see available attachments.

The account associated with the API key no longer exists.

Fix: The account may have been deleted. Create a new account at multimail.dev.

The specified API key ID does not exist or belongs to another tenant.

Fix: List your keys with GET /v1/api-keys.

The custom domain ID does not exist or belongs to another tenant.

Fix: List your domains with GET /v1/domains.

The webhook ID does not exist or belongs to another tenant.

Fix: List your webhooks with GET /v1/webhooks.

The email address you are trying to unsuppress is not on your suppression list.

Fix: List your suppression entries with GET /v1/suppression.

The billing session key has expired (1-hour TTL) or does not exist.

Fix: Complete payment within 1 hour of creating a checkout session.

Too many API requests in a short period. Separate limits apply to read and send operations.

Fix: Check the Retry-After header for seconds to wait. Implement exponential backoff.

The account has used all email sends for the current billing month.

Fix: Upgrade your plan for a higher quota. Check usage with GET /v1/usage.

New mailboxes have gradually increasing daily send limits to build sender reputation. You have hit today's cap.

Fix: Wait until midnight UTC (check Retry-After header). Daily limits increase automatically over 7 days. Check X-Warmup-Stage and X-Warmup-Daily-Limit headers.

The account has used all available storage (email bodies + attachments).

Fix: Upgrade your plan or delete old emails to free storage.

Too many failed activation code entries from this IP address (max 5 per hour).

Fix: Wait 1 hour and try again with the correct activation code.

A confirmation email was sent within the last 5 minutes.

Fix: Wait 5 minutes before requesting another confirmation email.

The account has reached its plan's mailbox limit (Starter: 2, Builder: 5, Pro: 25, Scale: 100).

Fix: Upgrade your plan via POST /v1/billing/checkout or delete unused mailboxes.

Custom domain creation is only available on Pro ($29/mo) and Scale ($99/mo) plans.

Fix: Upgrade to Pro or Scale to use custom domains.

A billing session key was requested but payment has not been processed yet.

Fix: Wait for payment processing to complete, then retry.

The mailbox's oversight mode is set to read_only, which blocks all outbound email.

Fix: Request an upgrade with POST /v1/mailboxes/{id}/request-upgrade. The response includes the upgrade path: gated_all > gated_send > monitored > autonomous.

The account operator has not yet entered the activation code sent to their oversight email.

Fix: Ask the operator to check their email for the activation code, then enter it at https://multimail.dev/confirm. Or call POST /v1/account/resend-confirmation.

Sending has been disabled by enforcement action (high bounce rate, spam complaints, or manual suspension).

Fix: Check the reason in the error message. Contact [email protected] for resolution.

Attempting to remove a suppression entry caused by a hard bounce (permanent delivery failure).

Fix: Hard bounce suppressions protect your sender reputation and cannot be removed. The recipient's email address is permanently invalid.

Another mailbox already uses this email address.

Fix: Choose a different address_local for your mailbox.

Another tenant has claimed this slug. The response includes available suggestions.

Fix: Use one of the suggested alternative slugs, or choose a different name.

The slug matches a reserved name (admin, api, mail, support, etc.). The response includes suggestions.

Fix: Use one of the suggested alternatives, or choose a different operator name.

This custom domain is already registered by another tenant.

Fix: Verify you own the domain and contact support if it was registered in error.

The email was already approved or rejected by another request (race condition with concurrent approvals).

Fix: No action needed. The email has already been processed.

An identical email (same recipients, subject, body) was sent within the last 60 seconds.

Fix: Wait 60 seconds, or use the idempotency_key field for intentional retries.

Only emails with pending_send_approval, pending_inbound_approval, or pending_scan status can be cancelled.

Fix: Check the email status. Already-sent or already-cancelled emails cannot be cancelled.

The request originates from a region subject to OFAC sanctions (Cuba, Iran, North Korea, Syria, Russia, Crimea, Donetsk, Luhansk).

Fix: MultiMail is not available in sanctioned regions per US export regulations.

An unhandled error occurred on the server. The stack trace is not exposed.

Fix: Retry the request. If persistent, contact [email protected] with the request details.

Internal configuration error: the Postmark webhook secret is missing from the environment.

Fix: This is a server configuration issue. Contact [email protected].

A request to the Stripe payment API failed.

Fix: Retry the billing request. If persistent, check Stripe status or contact support.

The Postmark domain API rejected the domain registration request.

Fix: Verify the domain name is valid and not already registered elsewhere. Retry after a few minutes.

The domain DNS verification check failed due to an upstream API error.

Fix: Ensure DNS records are properly configured, then retry POST /v1/domains/{id}/verify.