Requests and responses

Format

• JSON in and out. Send Content-Type: application/json with a body.
• Field names are snake_case. Times are ISO-8601 in UTC, like 2026-10-22T10:02:11Z.
• Money is in integer cents: 2900 is $29.00. Rates are fractions: 0.02 is 2%.
• Ids carry a prefix that says what they are: msg_, con_, lst_, seq_, bc_, wh_.

Idempotency

Every write accepts an Idempotency-Key header. Send the same key with the same body again and you get the first response back, with Idempotent-Replayed: true, and nothing happens twice. That makes retries safe: a timeout never means a duplicate email.

curl -X POST https://api.mailpark.io/v1/emails \
  -H "Authorization: Bearer $MAILPARK_API_KEY" \
  -H "Idempotency-Key: password-reset:user_123:abc" \
  -H "Content-Type: application/json" \
  -d '{"to":"jane@example.com","template":"password-reset"}'

• Keys last 24 hours and are scoped to the account.
• Reusing a key with a different body returns 409 idempotency_key_reused.
• A retry while the first request is still running returns 409 idempotency_in_progress.

Pagination

Lists come back in one shape. Pass ?limit= (default 50) and, for the next page, ?cursor= with the next_cursor you got. next_cursor is null on the last page.

{
  "data": [ { "id": "msg_01JB4Q7Z2K", "status": "delivered" } ],
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0yMlQxMDowMjoxMVoifQ"
}

next_steps

Many responses include next_steps: plain sentences saying what to do next, such as checking a delivery or verifying a domain. They're written for people and AI agents alike; show them, log them, or let your agent act on them.

Rate limits

Each account can make 50 requests a second. Every response carries the current state; going over returns 429 rate_limited.