Common transactional API errors

Successful transactional requests return 200 OK. If you get another response, something probably went wrong! This page can help you better understand and troubleshoot errors you receive from the transactional API.

Successful requests

A successful transactional API request returns a 200 OK and looks like this:

status: 200 OK
 "delivery_id": "A1C2E3jdieDks7zXdyz8XCFn1888",
 "queued_at": 1604977406

status: 405 Method Not Allowed

Possible misspelling of the request URI. The URI is or

status: 403 Forbidden

You probably need to take some additional steps to ensure that you’re authorized to send transactional messages.

Error MessageResolution
Account owner’s email address is not confirmed.Confirm your email address (or the email of the person who signed up for the account) to send messages. Look for the confirmation email in the inbox that you used when signin-up, or log in to trigger another email confirmation.
Account is not yet approved for sending.Verify your account to send messages. Learn more about why we verify accounts.
Workspace is set to “Do Not Send.”Update your Workspace Settings to send messages normally.

status: 401 Unauthorized

Invalid App API key. Check that your API key is correct and assigned to the correct workspace by visiting your Account API Credentials page. You may also have restricted your APP API keys to specific IP addresses.

status: 400 Bad Request

An invalid request is typically caused by missing, malformed, or invalid data. See below for common errors and fixes.

Error MessageResolution
Request entity must be JSON encoded and not exceed 2048 KB.Check that your request is less than 2MB and is formatted correctly. Extra spaces, missing commas, and extra/missing quotation marks may all cause the request to fail.
“from” address domain has not been verified.Verify your domain to send a message using the specified “from” address.
“transactional_message_id” not found.Check that you’re using a valid transactional_message_id in your workspace.
Missing required field“to” and “identifiers” are required fields. “from”, “subject”, and “body” are not required when using a transactional_message_id in your request and the message template has these values.
Invalid email address in fieldEmail addresses in “to”, “from”, “bcc”, and “reply-to” must be properly formatted. Use angled brackets and quote the “name” portion of an email address like "\"Name\" <>" to add a display name to an email address and avoid problems that might arise from special characters. Use commas to separate multiple email addresses.
Limit of 15 recipients exceeded.A single request can have up to 15 recipients across both “to” and “bcc” fields.
Invalid format in field “message_data”Check that the “message_data” is formatted correctly. Extra spaces, missing commas, and extra/missing quotation marks may cause the request to fail.
“Header” is a reserved header.Reserved headers cannot be overwritten. See a full list here.
Custom headers must be strings and not contain any non-ASCII characters.Headers must be comma-separated and consist of only ASCII characters.
Missing filename or content for attachment.Every attachment must have a filename and corresponding base64-encoded content.
Forbidden file typeSome filetypes are restricted from being sent as attachments. See full list here.
Attachment must be base64-encodedAttachments must be base64-encoded. See examples here.
Total attachment size exceeds 2048KB limit.Total attachments cannot exceed 2MB in size.
Invalid custom_payload or custom_data format.The value in the iOS and/or Android custom_payload and custom_data fields must be a string.

“View in browser” links do not work with Transactional messages that have Protect sensitive data enabled. We don’t retain protected messages, and cannot retrieve them.

Need help?

If you’ve encountered a different error, or need more help fixing one of these, please let us know!

Copied to clipboard!
Is this page helpful?