Transactional API - Common API errors

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

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

If your request is not successful, it may be due to one of the common errors listed in this guide.

status: 405 Method Not Allowed

Possible misspelling of the request URI. The URI should look like this: https://api.customer.io/v1/send/email.

status: 403 Forbidden

Your account may require additional steps before you’re authorized to send messages.

Error Message Resolution
Account owner’s email address is not confirmed. Confirm your email address (or the email of the person who signed up for the Customer.io 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 Message Resolution
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.id” 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 field Email addresses in “to”, “from”, “bcc”, and “reply-to” must be properly formatted. Use angled brackets like "Name <test@example.com>" to add a display name to an email address. Use commas to separate multiple email addresses in one field.
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 type Some filetypes are restricted from being sent as attachments. See full list here.
Attachment must be base64-encoded Attachments must be base64-encoded. See examples here.
Total attachment size exceeds 2048KB limit. Total attachments cannot exceed 2MB in size.

“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!