Batch, scheduling & idempotency

Batch sending

POST /emails/batch sends up to 100 emails in one request. Each item takes the same fields as POST /emails, except attachments and scheduled_at.

curl https://api.jumploon.com/emails/batch \
  -H "Authorization: Bearer $JUMPLOON_API_KEY" -H "Content-Type: application/json" \
  -d '[
    { "from": "Acme <hello@acme.com>", "to": ["ada@example.org"], "subject": "Hi Ada", "html": "<p>Hello Ada</p>" },
    { "from": "Acme <hello@acme.com>", "to": ["grace@example.org"], "subject": "Hi Grace", "html": "<p>Hello Grace</p>" }
  ]'
# → { "data": [{ "id": "…" }, { "id": "…" }] }

By default the batch is strict: if any email is invalid, none are sent and you get a 422 naming the bad one. To send the valid emails and get errors for the rest, add the header x-batch-validation: permissive:

{
  "data": [{ "id": "…" }],
  "errors": [{ "index": 1, "message": "The `to` field must contain at least one address." }]
}

Scheduling

Set scheduled_at to send later, up to 30 days ahead. It takes an ISO 8601 timestamp or a phrase of the form in <number> <unit>, such as minutes, hours or days:

{ "scheduled_at": "2026-11-01T09:00:00+01:00" }
{ "scheduled_at": "in 2 hours" }
{ "scheduled_at": "in 3 days" }

A scheduled email can be changed or canceled until its first delivery attempt:

# Reschedule
curl -X PATCH https://api.jumploon.com/emails/<id> \
  -H "Authorization: Bearer $JUMPLOON_API_KEY" -H "Content-Type: application/json" \
  -d '{ "scheduled_at": "in 1 day" }'
 
# Cancel
curl -X POST https://api.jumploon.com/emails/<id>/cancel \
  -H "Authorization: Bearer $JUMPLOON_API_KEY"

With the v3 API, use send_at (a Unix timestamp, up to 72 hours ahead).

Idempotency

Networks fail. If your request times out, you don't know whether the email was sent. Send an Idempotency-Key header and you can retry safely:

curl https://api.jumploon.com/emails \
  -H "Authorization: Bearer $JUMPLOON_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: receipt-1042" \
  -d '{ "from": "Acme <hello@acme.com>", "to": ["ada@example.org"], "subject": "Receipt #1042", "html": "…" }'

Repeating a key with the same request within 24 hours returns the first response. No second email is sent.
Repeating a key with a different request returns 409 Conflict.
Failed requests aren't remembered, so a request that failed can be retried with the same key.

Use something that identifies the action, such as receipt-<order id> or welcome-<user id>.