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`
`preview_text`	string	Optional	Inbox preview shown beside the subject in supported inboxes. Maximum 240 characters. Requires HTML or template_id and may use declared variables with a template.Example: `Your receipt and delivery details are inside.`
`html`	string	Direct content	HTML body when template_id is not used. Provide html, text, or both. Maximum 500,000 characters. RouteKite removes scripts, event handlers, embedded documents, forms, and unsafe URLs before the message is stored.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. Each dynamic image accepts one complete HTTPS URL variable and uses its saved fallback image when that value is omitted. Maximum encoded size is 100,000 characters.Example: `{ "product": { "image_url": "https://images.example.com/product.jpg" } }`
`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.

Control the inbox preview

Set preview_text to a short summary that supported inboxes can show beside the subject. RouteKite adds it as a hidden preheader without changing the visible message body.

When template_id is used, preview_text may use declared template variables. If omitted, the recipient application may choose text from the visible message body.

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.
402	`BALANCE_EXHAUSTED`	The billing account does not have enough prepaid balance for this email.	Add balance or reduce billable attachment usage before retrying.
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.
403	`BILLING_ACCOUNT_RESTRICTED`	Sending is restricted for this billing account.	Resolve the billing restriction before retrying.
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.