Programación de envíos

Añade scheduled_at a cualquier petición de envío para entregar más tarde. El correo se acepta de inmediato, recibe el estado scheduled y se dispara un webhook email.scheduled.

Formatos

Formato	Ejemplo
ISO 8601	2026-11-01T09:00:00Z, 2026-11-01T09:00:00+01:00
Lenguaje natural	in 30 seconds, in 10 minutes, in 2 hours, in 1 day, in 1 week

El lenguaje natural tiene la forma in <number> <unit>, donde la unidad es una de second, sec, minute, min, hour, hr, day, week (la s del plural es opcional). El texto no distingue entre mayúsculas y minúsculas.

Otras reglas:

• Máximo 30 días en el futuro. Más allá, la API devuelve 422 validation_error.
• Una hora en el pasado, o a menos de aproximadamente un segundo en el futuro, se trata como enviar ahora.
• Las cadenas ISO sin desfase de zona horaria las interpreta el analizador de fechas del servidor; incluye siempre Z o un desfase.
• Se aceptan tanto scheduled_at como scheduledAt.

Node.js

schedule.ts

import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data, error } = await spacepost.emails.send({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Your trial ends tomorrow",
  html: "<p>Reminder.</p>",
  scheduledAt: "in 1 day", // or an ISO date: "2026-11-01T09:00:00Z"
});

if (error) console.error(error);
else console.log("Scheduled", data.id);

cURL

curl -X POST https://api.spacepost.dev/emails \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": ["user@example.com"],
    "subject": "Your trial ends tomorrow",
    "html": "<p>Reminder.</p>",
    "scheduled_at": "2026-11-01T09:00:00Z"
  }'

Python

requests.post(
    "https://api.spacepost.dev/emails",
    headers={"Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}"},
    json={
        "from": "Acme <hello@acme.com>",
        "to": ["user@example.com"],
        "subject": "Your trial ends tomorrow",
        "html": "<p>Reminder.</p>",
        "scheduled_at": "in 1 day",
    },
)

Reprogramar

Solo se pueden modificar los correos con estado scheduled. PATCH /emails/{id} reemplaza la hora; se encola una nueva tarea y la anterior queda sin efecto.

Node.js

reschedule.ts

import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { error } = await spacepost.emails.update({
  id: "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10",
  scheduledAt: "in 2 hours",
});
if (error) console.error(error);

cURL

curl -X PATCH https://api.spacepost.dev/emails/$EMAIL_ID \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "2026-11-02T09:00:00Z" }'

Response (200)

{ "object": "email", "id": "0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10" }

Cancelar

Node.js

cancel.ts

import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { error } = await spacepost.emails.cancel("0192e1c4-7a3b-7c1e-9d2f-3b5a8e6f4c10");
if (error) console.error(error); // 422 validation_error if it is no longer scheduled

cURL

curl -X POST https://api.spacepost.dev/emails/$EMAIL_ID/cancel -H "Authorization: Bearer $SPACEPOST_API_KEY"

El estado pasa a canceled y el correo nunca se envía. Cancelar o reprogramar un correo que ya no está scheduled devuelve 422 validation_error (“Only scheduled emails can be canceled”).

Nota

Los destinatarios se descuentan de tu cuota cuando el correo se acepta, no cuando se envía. Por ahora, cancelar no devuelve cuota.

Por SMTP

Define el encabezado X-SpacePost-Scheduled-At con una fecha ISO o un valor en lenguaje natural. Consulta Relé SMTP.