Send an email

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

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

{
  "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.

{
  "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.

Getting Started

Guides

Endpoints

Webhooks

What it is

Before you begin

How it works

Request

Request fields

Example request

Response

Example response

Response fields

Personalize content

Delivery status

Limits and troubleshooting

​What it is

​Before you begin

​How it works

​Request

​Request fields

​Example request

​Response

​Example response

​Response fields

​Personalize content

​Delivery status

​Limits and troubleshooting

What it is

Before you begin

How it works

Request

Request fields

Example request

Response

Example response

Response fields

Personalize content

Delivery status

Limits and troubleshooting