# Programar Envios

La API de ReallyQuickEmails permite programar el envio de correos para una fecha y hora futura usando el endpoint `POST /send-email`. Puedes especificar la fecha de envio con timestamps ISO 8601 o con lenguaje natural.

## Campos relevantes

| Campo          | Tipo               | Descripcion                                                |
| -------------- | ------------------ | ---------------------------------------------------------- |
| `scheduled_at` | `string`           | Fecha y hora de envio. Acepta ISO 8601 o lenguaje natural. |
| `timezone`     | `string \| number` | Zona horaria para interpretar `scheduled_at`. Opcional.    |

## Formato de `scheduled_at`

### Timestamps ISO 8601

Puedes especificar una fecha y hora exacta en formato ISO 8601, incluyendo el offset de zona horaria:

```
"2025-10-16T15:00:00+09:00"
"2025-12-25T09:00:00-03:00"
"2026-01-15T08:30:00Z"
```

### Lenguaje natural

Tambien puedes usar expresiones en lenguaje natural. La API las interpreta en relacion al momento actual:

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

Cuando usas lenguaje natural, el campo `timezone` determina como se interpreta la hora. Si no se especifica, se usa la zona horaria por defecto del proyecto (`default_timezone`).

## Formato de `timezone`

El campo `timezone` acepta varios formatos:

| Formato             | Ejemplo                              |
| ------------------- | ------------------------------------ |
| Nombre IANA         | `"America/Santiago"`, `"Asia/Tokyo"` |
| Offset UTC (string) | `"+09:00"`, `"-03:00"`               |
| Horas numericas     | `9`, `-3`                            |

Si no se incluye `timezone` en la solicitud, la API usa el valor de `default_timezone` configurado en el proyecto.

## Validacion

La fecha programada debe ser en el futuro. Si `scheduled_at` resuelve a una fecha en el pasado, la API retorna un error `400 Bad Request`.

## Procesamiento

Los correos programados son procesados por un worker en segundo plano que ejecuta cada 30 segundos. Esto significa que un correo programado puede enviarse hasta 30 segundos despues de la hora programada.

## Respuesta

Cuando se programa un correo exitosamente, la respuesta incluye los siguientes campos:

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

## Ejemplos

### Programar con timestamp ISO 8601

```bash
curl -X POST https://api.reallyquickemails.com/send-email \
  -H "Content-Type: application/json" \
  -H "x-project-id: proj_abc123" \
  -d '{
    "recipient": "cliente@ejemplo.com",
    "sender": "ventas@mitienda.com",
    "senderName": "Mi Tienda",
    "subject": "Recordatorio de cita",
    "templateId": "recordatorio-cita",
    "scheduled_at": "2025-10-16T15:00:00+09:00"
  }'
```

Respuesta:

```json
{
  "success": true,
  "scheduled": true,
  "scheduled_send_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "scheduled_for": "2025-10-16T06:00:00.000Z",
  "scheduled_for_local": "2025-10-16 15:00 (Asia/Tokyo)",
  "timezone": "Asia/Tokyo",
  "message": "Correo programado para 2025-10-16 15:00 (Asia/Tokyo)"
}
```

### Programar con lenguaje natural y zona horaria

```bash
curl -X POST https://api.reallyquickemails.com/send-email \
  -H "Content-Type: application/json" \
  -H "x-project-id: proj_abc123" \
  -d '{
    "recipient": "cliente@ejemplo.com",
    "sender": "ventas@mitienda.com",
    "senderName": "Mi Tienda",
    "subject": "Oferta especial",
    "templateId": "oferta-especial",
    "scheduled_at": "tomorrow at 3pm",
    "timezone": "America/Santiago"
  }'
```

Respuesta:

```json
{
  "success": true,
  "scheduled": true,
  "scheduled_send_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "scheduled_for": "2025-10-17T18:00:00.000Z",
  "scheduled_for_local": "2025-10-17 15:00 (America/Santiago)",
  "timezone": "America/Santiago",
  "message": "Correo programado para 2025-10-17 15:00 (America/Santiago)"
}
```

### Programar con offset numerico

```bash
curl -X POST https://api.reallyquickemails.com/send-email \
  -H "Content-Type: application/json" \
  -H "x-project-id: proj_abc123" \
  -d '{
    "recipient": "cliente@ejemplo.com",
    "sender": "ventas@mitienda.com",
    "senderName": "Mi Tienda",
    "subject": "Seguimiento",
    "templateId": "seguimiento",
    "scheduled_at": "next monday at 9am",
    "timezone": -3
  }'
```

Respuesta:

```json
{
  "success": true,
  "scheduled": true,
  "scheduled_send_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "scheduled_for": "2025-10-20T12:00:00.000Z",
  "scheduled_for_local": "2025-10-20 09:00 (UTC-3)",
  "timezone": "UTC-3",
  "message": "Correo programado para 2025-10-20 09:00 (UTC-3)"
}
```


---

# 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/guias/scheduling.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.