Schedule email

Schedule a message for future delivery by passing scheduled_at as an ISO-8601 UTC timestamp.

Step-by-step

1. Choose a future timestamp

Use UTC, e.g. 2026-06-15T15:00:00Z. Timestamps in the past (beyond a 60-second skew tolerance) are rejected.

2. Send with scheduled_at

Include scheduled_at on POST /emails along with your normal fields. Omit it for immediate queueing.

The API returns status scheduled until the worker dispatches the message.

3. Cancel if plans change

While status is still scheduled, call:

POST /emails/{id}/cancel

The message moves to status cancelled and will not send.

4. Monitor status

Poll GET /emails/{id} or subscribe to webhooks for status transitions.

Status flow

scheduled → queued → sent → delivering → delivered (or failed / bounced)

Sending introduction — full lifecycle table
Batch sending — many scheduled sends

Example request

curl -sS -X POST "https://api.piisend.com/api/v1/emails" \
  -H "Authorization: Bearer $PIISEND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": ["user@example.com"],
    "subject": "Reminder tomorrow",
    "text": "Your appointment is at 3pm.",
    "scheduled_at": "2026-06-15T15:00:00Z"
  }'