# Enviar Email

`POST /send-email`

Endpoint principal para enviar correos electronicos. Soporta envio inmediato, programado, con plantillas Handlebars, adjuntos y multiples destinatarios.

***

## Autenticacion

Este endpoint no requiere autenticacion mediante API key. Se recomienda incluir el header `x-project-id` para asociar el envio a un proyecto especifico y habilitar tracking de actividad.

> **Nota:** Este endpoint es de uso interno. Para enviar correos desde tu aplicacion, utiliza los endpoints de la [API Publica v1](/reallyquickemails-docs/referencia-api/public-api.md) que requieren autenticacion con Bearer token.

## Headers

| Header         | Tipo   | Requerido | Descripcion                                     |
| -------------- | ------ | --------- | ----------------------------------------------- |
| `x-project-id` | string | No        | ID del proyecto. Asocia el envio a un proyecto. |
| `x-source`     | string | No        | Identificador del origen de la solicitud.       |
| `Content-Type` | string | Si        | Debe ser `application/json`.                    |

## Request Body

| Campo               | Tipo                | Requerido | Descripcion                                                                   |
| ------------------- | ------------------- | --------- | ----------------------------------------------------------------------------- |
| `html`              | string              | Si\*      | Contenido HTML del correo. Requerido si no se usa `templateId`.               |
| `subject`           | string              | Si        | Asunto del correo.                                                            |
| `recipient`         | string \| string\[] | Si        | Direccion de correo del destinatario, o un array de direcciones.              |
| `sender`            | string              | Si        | Direccion de correo del remitente.                                            |
| `senderName`        | string              | No        | Nombre visible del remitente.                                                 |
| `templateId`        | string              | No        | ID de una plantilla almacenada. Si se proporciona, se usa en lugar de `html`. |
| `data`              | object              | No        | Objeto con variables para sustitucion Handlebars en la plantilla o HTML.      |
| `email_type`        | string              | No        | Tipo de correo (ej. `transactional`, `marketing`, `automation`).              |
| `campaign_id`       | string              | No        | UUID de la campana asociada.                                                  |
| `automation_run_id` | string              | No        | UUID de la ejecucion de automatizacion asociada.                              |
| `scheduled_at`      | string              | No        | Fecha/hora de envio programado. Ver seccion de programacion.                  |
| `timezone`          | string              | No        | Zona horaria para interpretar `scheduled_at`. Ver seccion de programacion.    |
| `cc`                | string \| string\[] | No        | Direccion(es) de correo en copia.                                             |
| `bcc`               | string \| string\[] | No        | Direccion(es) de correo en copia oculta.                                      |
| `attachments`       | array               | No        | Lista de objetos de adjuntos. Maximo 10 adjuntos.                             |

## Reply-To Automatico (Inbound Email)

Cuando se envia un correo con `x-project-id`, el sistema genera automaticamente un header `Reply-To` con el nombre del remitente y una direccion de enrutamiento interna:

```
Reply-To: "Mi Tienda" <r-x7K9mP2q@rqe.inbound.reallyquickemails.com>
```

Los clientes de correo (Gmail, Outlook, Apple Mail) muestran el **nombre del remitente** en lugar de la direccion tecnica. Cuando el destinatario responde, la respuesta se enruta automaticamente a los servidores de ReallyQuickEmails y se asocia al hilo de conversacion original.

Este comportamiento es automatico y no requiere configuracion adicional. Para mas detalles sobre el procesamiento de correos entrantes, consulta [POST /api/inbound/ses](/reallyquickemails-docs/referencia-api/webhooks.md#post-apiinboundses).

***

## Adjuntos

Cada objeto en el array `attachments` tiene la siguiente estructura:

| Campo         | Tipo   | Requerido | Descripcion                                                                                |
| ------------- | ------ | --------- | ------------------------------------------------------------------------------------------ |
| `filename`    | string | Si        | Nombre del archivo (ej. `factura.pdf`).                                                    |
| `url`         | string | No\*      | URL publica del archivo. Requerido si no se proporciona `content`.                         |
| `content`     | string | No\*      | Contenido del archivo codificado en Base64. Requerido si no se proporciona `url`.          |
| `contentType` | string | No        | Tipo MIME del archivo (ej. `application/pdf`). Se infiere del nombre si no se proporciona. |

**Limites:**

* Maximo **10 adjuntos** por correo.
* Maximo **10 MB** por adjunto individual.

## Programacion de Envio

El campo `scheduled_at` soporta multiples formatos:

### Timestamp ISO 8601

```
"scheduled_at": "2025-03-15T14:30:00Z"
```

### Lenguaje natural (ingles)

```
"scheduled_at": "tomorrow at 3pm"
"scheduled_at": "in 2 hours"
"scheduled_at": "next monday at 9am"
```

### Zona horaria (`timezone`)

El campo `timezone` se usa para interpretar correctamente `scheduled_at`. Soporta:

* **Nombre IANA:** `"America/Santiago"`, `"US/Eastern"`, `"Europe/Madrid"`
* **Offset UTC:** `"UTC-3"`, `"UTC+5:30"`
* **Numerico:** `-3`, `5.5`

Si no se proporciona `timezone`, se usa la zona horaria por defecto del proyecto (`default_timezone`). Si el proyecto no tiene zona horaria configurada, se asume UTC.

***

## Ejemplo de Solicitud

### Envio inmediato

```bash
curl -X POST https://api.reallyquickemails.com/send-email \
  -H "Content-Type: application/json" \
  -H "x-project-id: proj_abc123" \
  -d '{
    "html": "<h1>Hola {{nombre}}</h1><p>Tu pedido #{{pedido}} esta en camino.</p>",
    "subject": "Tu pedido esta en camino",
    "recipient": "cliente@ejemplo.com",
    "sender": "ventas@mitienda.com",
    "senderName": "Mi Tienda",
    "data": {
      "nombre": "Juan",
      "pedido": "12345"
    },
    "email_type": "transactional"
  }'
```

### Envio programado con adjuntos

```bash
curl -X POST https://api.reallyquickemails.com/send-email \
  -H "Content-Type: application/json" \
  -H "x-project-id: proj_abc123" \
  -d '{
    "subject": "Reporte mensual - Marzo 2025",
    "recipient": ["gerente@empresa.com", "director@empresa.com"],
    "sender": "reportes@empresa.com",
    "senderName": "Sistema de Reportes",
    "templateId": "reporte-mensual",
    "data": {
      "mes": "Marzo",
      "anio": "2025"
    },
    "scheduled_at": "next monday at 9am",
    "timezone": "America/Santiago",
    "attachments": [
      {
        "filename": "reporte-marzo-2025.pdf",
        "url": "https://storage.ejemplo.com/reportes/marzo-2025.pdf",
        "contentType": "application/pdf"
      }
    ]
  }'
```

***

## Respuestas

### Envio inmediato exitoso

```json
{
  "success": true,
  "messageId": "0102018e-abcd-1234-5678-9abcdef01234",
  "activityId": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
  "message": "Email sent successfully"
}
```

Si el correo incluye adjuntos, se agrega el campo `attachments_sent`:

```json
{
  "success": true,
  "messageId": "0102018e-abcd-1234-5678-9abcdef01234",
  "activityId": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
  "message": "Email sent successfully",
  "attachments_sent": 2
}
```

| Campo              | Tipo           | Descripcion                                                                                     |
| ------------------ | -------------- | ----------------------------------------------------------------------------------------------- |
| `messageId`        | string         | ID del mensaje asignado por AWS SES.                                                            |
| `activityId`       | string \| null | UUID del registro de actividad en la base de datos. `null` si no se proporciono `x-project-id`. |
| `attachments_sent` | number         | Cantidad de adjuntos enviados. Solo presente si se enviaron adjuntos.                           |

### Envio programado exitoso

```json
{
  "success": true,
  "scheduled": true,
  "scheduled_send_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scheduled_for": "2025-03-17T12:00:00.000Z",
  "scheduled_for_local": "2025-03-17 09:00 (America/Santiago)",
  "timezone": "America/Santiago",
  "message": "Correo programado para 2025-03-17 09:00 (America/Santiago)"
}
```

| Campo                 | Tipo   | Descripcion                                                              |
| --------------------- | ------ | ------------------------------------------------------------------------ |
| `scheduled_send_id`   | string | UUID del correo programado en la base de datos.                          |
| `scheduled_for`       | string | Fecha y hora de envio en UTC (ISO 8601).                                 |
| `scheduled_for_local` | string | Fecha y hora de envio en la zona horaria especificada (formato legible). |
| `timezone`            | string | Zona horaria utilizada para la programacion.                             |

***

## Verificacion de Remitente

Cuando se incluye el header `x-project-id`, el endpoint valida que el remitente (`sender`) este verificado antes de encolar el envio. Se verifica en este orden:

1. **Email verificado** — El email existe en `sender_profiles` con `email_verified = true` (verificacion via magic link).
2. **Dominio autenticado** — El dominio del email esta registrado en `identities` con `verification_status = verified` (verificacion DNS completa).

Si ninguna de las dos condiciones se cumple, se retorna un error `403`:

```json
{
  "error": "Sender \"ventas@mitienda.com\" is not verified. Verify the email via magic link or authenticate the domain \"mitienda.com\" first.",
  "code": "SENDER_NOT_VERIFIED"
}
```

> **Nota:** Para verificar un email como remitente, usa [POST /domains/verify-email](/reallyquickemails-docs/referencia-api/domains.md#post-domainsverify-email). Para verificar un dominio completo (recomendado para mejor deliverability), usa [POST /domains/register](/reallyquickemails-docs/referencia-api/domains.md#post-domainsregister).

***

## Codigos de Error

| Codigo | Descripcion                                                                                             |
| ------ | ------------------------------------------------------------------------------------------------------- |
| `400`  | Solicitud invalida. Faltan campos requeridos, formato incorrecto, o fecha programada en el pasado.      |
| `403`  | Remitente no verificado. El email o dominio del sender no esta verificado. Ver seccion de verificacion. |
| `404`  | Plantilla no encontrada (cuando se usa `templateId`).                                                   |
| `413`  | Adjunto excede el limite de tamano (10 MB).                                                             |
| `415`  | Tipo de contenido no soportado. Se requiere `application/json`.                                         |
| `500`  | Error interno del servidor.                                                                             |
| `502`  | Error de comunicacion con el servicio de envio de correo (AWS SES).                                     |
| `504`  | Timeout en la comunicacion con el servicio de envio de correo.                                          |

### Ejemplo de error

```json
{
  "success": false,
  "error": "Missing required field: subject"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://reallyquickemails.gitbook.io/reallyquickemails-docs/referencia-api/send-email.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.