Common transactional API errors
UpdatedSuccessful 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 https://api.customer.io/v1/send/email or https://api.customer.io/v1/send/push.
status: 403 Forbidden
You probably need to take some additional steps to ensure that you’re authorized to send transactional 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” 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 and quote the “name” portion of an email address like "\"Name\" <test@example.com>" 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 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. |
| 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
“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!
