Emails

Send an email

Validate and queue one transactional email for one recipient.

POST/api/v1/emails

On this page

Authentication

Send a RouteKite API key as a Bearer token. This endpoint requires the email:send scope.

Required headers
Name	Type	Requirement	Description
`Authorization`	string	Required	Bearer API key with the required workspace scope.Example: `Bearer rk_your_key`
`Idempotency-Key`	string	Required	Stable key between 8 and 200 characters.Example: `order-123-confirmation`
`Content-Type`	string	Required	Must be application/json.Example: `application/json`

Request body

Request fields
Name	Type	Requirement	Description
`from`	email	Required	A verified RouteKite Sending Address. Maximum 320 characters.Example: `updates@example.com`
`to`	email	Required	Exactly one recipient. Maximum 320 characters.Example: `customer@example.net`
`reply_to`	email	Optional	Override where replies are delivered for this message.Example: `support@example.com`
`subject`	string	Direct content	The message subject when template_id is not used. Between 1 and 998 characters.Example: `Your order is confirmed`
`html`	string	Direct content	HTML body when template_id is not used. Provide html, text, or both. Maximum 500,000 characters.Example: `<h1>Thank you</h1>`
`text`	string	Direct content	Plain-text body when template_id is not used. Provide html, text, or both. Maximum 200,000 characters.Example: `Thank you. Your order is confirmed.`
`template_id`	uuid	Template content	A published transactional template in this workspace.
`template_version_id`	uuid	Optional	Pin an immutable published version. Omit it to use the current published version.
`variables`	object	Optional	Values used to render template variables and lists. Maximum encoded size is 100,000 characters.
`metadata`	object	Optional	Small correlation values. Keys are limited to 80 characters and string values to 500 characters.Example: `{ "order_id": "ord_123" }`
`attachments`	(uuid \| direct attachment)[]	Optional	Up to 10 uploaded attachment IDs, direct Base64 files, or both in delivery order.Example: `[{ "filename": "notes.txt", "content_type": "text/plain", "content": "SGVsbG8=" }]`
`attachments[].filename`	string	Direct file	Filename with a supported extension. Maximum 255 characters.Example: `invoice.pdf`
`attachments[].content_type`	string	Direct file	Exact supported MIME type matching the file content and extension.Example: `application/pdf`
`attachments[].content`	Base64 string	Direct file	Standard Base64 only. Data URLs and files larger than 5,000,000 decoded bytes are rejected.

Response

Response fields
Name	Type	Requirement	Description
`id`	uuid	Always	The RouteKite message identifier.
`object`	string	Always	Always email.
`status`	string	Always	The current state, normally queued on acceptance.
`created_at`	date-time	Always	When RouteKite accepted the message.

Behavior

RouteKite validates the key, Sending Address, recipient, readiness, suppression state, content, attachments, limits, and idempotency before creating a message.

Errors

Status	Code	What it means	What to do
400	`INVALID_REQUEST`	A required value is missing or invalid.	Correct the first validation message.
400	`IDEMPOTENCY_KEY_REQUIRED`	The idempotency key is missing or invalid.	Send a stable key between 8 and 200 characters.
401	`UNAUTHORIZED`	The API key is missing, invalid, revoked, or expired.	Check the Bearer header and active key.
403	`FORBIDDEN`	The key lacks email:send access.	Use a key with the required scope.
403	`SENDING_PAUSED`	Workspace sending is paused.	Resolve the active sending notice in RouteKite.
409	`IDEMPOTENCY_CONFLICT`	The key was reused with changed content.	Reuse the original payload or create a new key.
409	`ATTACHMENT_NOT_READY`	An attachment has not completed validation.	Complete the attachment before sending.
410	`ATTACHMENT_EXPIRED`	A referenced attachment is no longer retained.	Prepare a new attachment.
413	`ATTACHMENT_LIMIT_EXCEEDED`	The attachment count or size exceeds the limit.	Use no more than 10 files totaling 10 MB.
413	`PAYLOAD_TOO_LARGE`	The encoded email request exceeds 16,000,000 bytes.	Use an uploaded attachment ID or reduce the request.
413	`STORAGE_LIMIT_EXCEEDED`	The account storage allowance cannot accept the temporary file.	Remove unused files or use a smaller attachment.
422	`ATTACHMENT_INVALID`	Base64, signature, extension, or content type validation failed.	Encode the original supported file as standard Base64 and keep its metadata exact.
422	`ATTACHMENT_TYPE_UNSUPPORTED`	The file format is not supported.	Use one of the documented attachment formats.
422	`SENDER_UNAVAILABLE`	The Sending Address cannot send.	Verify it or choose another address.
422	`TEMPLATE_UNAVAILABLE`	The transactional template is not published or available.	Publish the template or check its ID.
422	`INVALID_TEMPLATE_DATA`	Required variables are missing or invalid.	Provide values matching the template variable definitions.
429	`DAILY_LIMIT_REACHED`	The workspace reached its current daily limit.	Wait for the limit window to reset.
429	`RATE_LIMITED`	Too many requests were sent in a short period.	Honor Retry-After before retrying.
500 / 503	`INTERNAL_ERROR`	RouteKite could not accept the message.	Retry cautiously with the same idempotency key.