> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ycloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Send an email

> Send HTML or plain-text email and track delivery for each recipient.

## What it is

The Email API sends one email to one or more recipients. Use it for
transactional notifications, account updates, receipts, and personalized
messages.

## Before you begin

* Store your YCloud API key in `YCLOUD_API_KEY`.
* Register and activate the sender domain in your YCloud account.
* Use a sender address from the activated domain.
* Prepare HTML or plain-text content no larger than 150 KB.

## How it works

Send the email with `POST /emails`. The response confirms that YCloud accepted
the email and returns its `id`. Delivery happens separately for each address in
`to`, `cc`, and `bcc`.

Subscribe to `email.delivery.updated` to receive recipient-level states such as
`sent`, `delivered`, `undelivered`, and `failed`.

## Request

`POST /emails`

### Request fields

| Field | Required | Description |
| - | - | - |
| `from` | Yes | Sender address on an activated domain. A display name is optional. |
| `to` | Yes | One or more comma-separated recipient addresses. Maximum 100 addresses. |
| `subject` | Yes | Subject line. Maximum 255 characters. |
| `content` | Yes | HTML or plain-text body. Maximum size 150 KB. |
| `contentType` | No | `text/html` or `text/plain`. Defaults and tracking behavior depend on the content type. |
| `cc` | No | Comma-separated carbon-copy recipients. |
| `bcc` | No | Comma-separated blind-carbon-copy recipients. |
| `replyTo` | No | Address used when a recipient replies. |
| `summary` | No | Short email summary. Maximum 70 characters. |
| `variables` | No | One personalization object for each address in `to`. |
| `externalId` | No | Your unique reference for reconciling the email with an internal record. |
| `callbackUrl` | No | Per-message delivery report URL. Use Webhook endpoints for new integrations. |

### Example request

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST https://api.ycloud.com/v2/emails \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "Support Team<support@example.com>",
    "to": "customer@example.com",
    "subject": "Welcome",
    "contentType": "text/html",
    "content": "<h1>Welcome</h1><p>Thanks for joining us.</p>",
    "externalId": "welcome-10001"
  }'
```

## Response

A successful response returns the created email object. Acceptance does not
mean that every recipient has received the email.

### Example response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "EMAIL_ID",
  "from": {
    "address": "support@example.com",
    "name": "Support Team"
  },
  "to": [
    {
      "address": "customer@example.com"
    }
  ],
  "subject": "Welcome",
  "contentType": "text/html",
  "externalId": "welcome-10001",
  "totalRecipients": 1,
  "createTime": "2026-07-16T12:00:00.000Z"
}
```

### Response fields

| Field | Description |
| - | - |
| `id` | YCloud email ID. Store it to correlate recipient delivery events. |
| `from` | Parsed sender mailbox. |
| `to`, `cc`, `bcc` | Parsed recipient mailboxes. |
| `contentType` | MIME type used for the email body. |
| `totalRecipients` | Total number of recipients across `to`, `cc`, and `bcc`. |
| `totalPrice` | Total email price when available. |
| `currency` | ISO 4217 price currency. |
| `createTime` | Email creation time in RFC 3339 format. |
| `externalId` | The reference supplied in the request. |

## Personalize content

Place variables between `#` characters in the content. Provide one variable
object for each address in `to`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "to": "alice@example.com,bob@example.com",
  "content": "Hello #name#!",
  "variables": [
    { "name": "Alice" },
    { "name": "Bob" }
  ]
}
```

## Delivery status

Subscribe to `email.delivery.updated`. Each event identifies the email and the
specific `recipientAddress`, because recipients can have different final
states.

`text/plain` messages do not generate click or open tracking events.

## Limits and troubleshooting

* The sender domain must be activated before sending.
* `to` supports at most 100 addresses.
* `subject` supports at most 255 characters.
* `content` supports at most 150 KB.
* A successful API response can still be followed by an `undelivered` or
  `failed` recipient event.
* Use the email `id`, recipient address, and `externalId` when investigating
  delivery.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.