> ## 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.

# Enviar un correo electrónico

> Enviar correos electrónicos en HTML o texto sin formato y realizar un seguimiento de la entrega para cada destinatario.

## Qué es

La API de correo electrónico envía un correo a uno o más destinatarios. Úsela para
notificaciones transaccionales, actualizaciones de cuenta, recibos y
mensajes personalizados.

## Antes de empezar

* Guarde su clave de API de YCloud en `YCLOUD_API_KEY`.
* Registre y active el dominio del remitente en su cuenta de YCloud.
* Utilice una dirección de remitente del dominio activado.
* Prepare contenido HTML o de texto sin formato que no supere los 150 KB.

## Cómo funciona

Envíe el correo electrónico con `POST /emails`. La respuesta confirma que YCloud aceptó
el correo electrónico y devuelve su `id`. La entrega se realiza por separado para cada dirección en
`to`, `cc` y `bcc`.

Suscríbase a `email.delivery.updated` para recibir estados a nivel de destinatario como
`sent`, `delivered`, `undelivered` y `failed`.

## Solicitud

`POST /emails`

### Campos de la solicitud

| Campo | Obligatorio | Descripción |
| - | - | - |
| `from` | Sí | Dirección del remitente en un dominio activado. El nombre para mostrar es opcional. |
| `to` | Sí | Una o más direcciones de destinatarios separadas por comas. Máximo 100 direcciones. |
| `subject` | Sí | Línea de asunto. Máximo 255 caracteres. |
| `content` | Sí | Cuerpo en HTML o texto sin formato. Tamaño máximo de 150 KB. |
| `contentType` | No | `text/html` o `text/plain`. Los valores predeterminados y el comportamiento de seguimiento dependen del tipo de contenido. |
| `cc` | No | Destinatarios de copia al carbón separados por comas. |
| `bcc` | No | Destinatarios de copia oculta separados por comas. |
| `replyTo` | No | Dirección utilizada cuando un destinatario responde. |
| `summary` | No | Breve resumen del correo electrónico. Máximo 70 caracteres. |
| `variables` | No | Un objeto de personalización para cada dirección en `to`. |
| `externalId` | No | Su referencia única para conciliar el correo electrónico con un registro interno. |
| `callbackUrl` | No | URL del informe de entrega por mensaje. Utilice puntos de enlace de Webhook para nuevas integraciones. |

### Ejemplo de solicitud

```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"
  }'
```

## Respuesta

Una respuesta exitosa devuelve el objeto de correo electrónico creado. La aceptación no
significa que cada destinatario haya recibido el correo electrónico.

### Ejemplo de respuesta

```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"
}
```

### Campos de respuesta

| Campo | Descripción |
| - | - |
| `id` | ID de correo electrónico de YCloud. Guárdelo para correlacionar los eventos de entrega del destinatario. |
| `from` | Buzón del remitente analizado. |
| `to`, `cc`, `bcc` | Buzones de los destinatarios analizados. |
| `contentType` | Tipo MIME utilizado para el cuerpo del correo electrónico. |
| `totalRecipients` | Número total de destinatarios en `to`, `cc` y `bcc`. |
| `totalPrice` | Precio total del correo electrónico cuando esté disponible. |
| `currency` | Moneda del precio en formato ISO 4217. |
| `createTime` | Hora de creación del correo electrónico en formato RFC 3339. |
| `externalId` | La referencia proporcionada en la solicitud. |

## Personalizar contenido

Coloque las variables entre los caracteres `#` en el contenido. Proporcione un
objeto de variable para cada dirección en `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" }
  ]
}
```

## Estado de entrega

Suscríbete a `email.delivery.updated`. Cada evento identifica el correo electrónico y el
`recipientAddress` específico, porque los destinatarios pueden tener diferentes
estados finales.

Los mensajes `text/plain` no generan eventos de seguimiento de clics o aperturas.

## Límites y solución de problemas

* El dominio del remitente debe estar activado antes de enviar.
* `to` admite un máximo de 100 direcciones.
* `subject` admite un máximo de 255 caracteres.
* `content` admite un máximo de 150 KB.
* Una respuesta exitosa de la API aún puede ir seguida de un `undelivered` o
  evento de destinatario `failed`.
* Utilice el `id` del correo electrónico, la dirección del destinatario y el `externalId` al investigar
  la entrega.


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