---
title: "Send a single email"
method: POST
path: "/v2/{sid}/email/messages"
tags: ["Email"]
---

# Send a single email

`POST /v2/{sid}/email/messages`

## Request

- Base URL: `https://api.in.kaleyra.io`
- URL: `https://api.in.kaleyra.io/v2/{sid}/email/messages`
- Auth: none declared. Required headers: `api-key`, `Content-Type`

Send one email payload to one or more recipients (To/CC/BCC). Attachments supported; total payload ≤ 20 MB.

## Path parameters

- `sid` string, required

## Headers

- `api-key` string, required
- `Content-Type` string, required

## Request body

- EmailRequest: Email payload for single email sending.
  - `from` string, required: Sender email address; domain must be whitelisted on your account.
  - `from_name` string: Display name shown to recipients.
  - `to` string, required: Comma-separated list of recipients (max 50 addresses).
  - `cc` string: Comma-separated CC recipients (max 50 addresses).
  - `bcc` string: Comma-separated BCC recipients (max 50 addresses).
  - `subject` string: Email subject. When using templates, the API subject overrides the template subject if present.
  - `tag` string: Category/label for the email (for reporting/segmentation).
  - `type` 'OTP' | 'MKT' | 'TXN': Email type; defaults to `MKT` if omitted.
  - `priority` integer: Send priority (implementation-specific; higher values may be processed first).
  - `html_body` string: HTML content of the message (≤ ~5 MB). Preferred for tracking.
  - `html_content` string: Plain-text body companion to `html_body` (e.g. multipart/alternative text part). Distinct from `text_body` in some integrations.
  - `text_body` string: Plain text content (≤ ~5 MB). Used by clients that don’t support HTML.
  - `reply_to` string: Reply-to address to receive responses.
  - `dynamic_content` boolean: Set `true` to enable `params` substitution in subject/body (use `{{key}}` placeholders).
  - `params` object: Key-value pairs for dynamic substitution (≤ 20 keys; key ≤ 20 chars; value ≤ 4000 chars).
  - `attachments` Attachment[]: Attach files in JSON requests by absolute URL or Base64 content. For local file uploads, use `multipart/form-data` with repeated `file` fields. Overall email (text + html + attachments) ≤ 20 MB.
    - `content` string, required: Absolute URL or Base64 content.
    - `content_type` string: MIME type of the attachment.
    - `filename` string, required: File name to present to the recipient.
  - `callback_profile_id` string: Callback profile ID configured for webhook notifications.
  - `ref` string: Optional contextual reference (e.g., campaign name).
  - `ref1` string: Optional contextual reference (e.g., customer ID).
  - `ref2` string: Optional contextual reference.
  - `ref3` string: Optional third contextual reference (e.g. segment or batch id).
  - `template_id` string: Template ID to use; API fields override template fields where present.
  - `template_name` string: Name of a saved template to use (alternative to `template_id`). API fields override template fields where present.
  - `webhook_id` string: Optional webhook identifier if supported on your account.
  - `metadata` object: Free-form metadata echoed in logs/callbacks (if enabled).

## Response `202`

Request accepted; messages queued for delivery.

- ApiResponse: Standard success response envelope.
  - `data` MessageRecord[]: Array of message records.
    - `message_id` string: Unique identifier of the queued message.
    - `to` string: Resolved recipient(s) for this message record.
    - `cc` string: CC recipients for this message record (if any).
    - `bcc` string: BCC recipients for this message record (if any).
    - `from` string: Sender address used.
    - `subject` string: Subject line used.
  - `error` object, nullable: Error details, if any (usually empty on success).

## Other responses

- `400`: Bad Request - validation error.
- `401`: Unauthorized - incorrect SID or API key.
- `413`: Payload Too Large - overall request exceeded limits (e.g., attachments + bodies > 20 MB).
- `500`: Internal Server Error

---

[API](https://skmtc.dev/kaleyra/apis/email-api-v2.md) - [All operations](https://skmtc.dev/kaleyra/apis/email-api-v2/llms.txt) - [OpenAPI document](https://skmtc.dev/kaleyra/apis/email-api-v2/revisions/22b4be0d0455?raw)