Errors, limits and headers

Requests

• Send JSON with Content-Type: application/json, and ask for JSON back with Accept: application/json.
• Call us over https.
• Times are ISO 8601 with a timezone, for example 2026-10-05T09:00:00-04:00. Times we send back are in UTC.
• An id in a path is used exactly as we gave it to you. An email address in a path is URL encoded, so sam@example.com becomes sam%40example.com.

Errors

Every error we return from /api/v1 has the same shape, so your code only needs one handler:

{
  "error": {
    "type": "invalid_request",
    "message": "The to field must be an array.",
    "fields": {
      "to": ["The to field must be an array."]
    },
    "request_id": "0f5b6c1e-2d3a-4b8c-9e7f-1a2b3c4d5e6f"
  }
}

• type is stable and safe to branch on. message is written for a person and can change wording, so log it rather than matching on it.
• fields appears when a rule on a named field failed, one entry per field. In a batch the name includes the position, as in emails.3.to.
• request_id identifies the call. See finding a call again.

A 500, 502 or 503 means something went wrong on our side or with the mail network, and a 500 may arrive without the body above. Retry those with backoff. With an Idempotency-Key, a retry of a request that did go through gets the original answer instead of a second send.

Rate limits

Each account can make 120 requests a minute across the email and newsletter APIs together. Every key on the account shares that budget.

Past the limit you get a 429 with the type rate_limited and a Retry-After header saying how many seconds to wait. Successful responses carry X-RateLimit-Limit and X-RateLimit-Remaining, so a busy integration can slow down before it hits the ceiling.

If you need to send a large number of similar messages, use a batch: up to 100 messages count as one request.

Idempotency

Networks drop. When your code retries a request it is not sure went through, send an Idempotency-Key header with a value unique to that one piece of work, such as an order number:

Idempotency-Key: receipt-1042

For 24 hours, the same key with the same request body gets the original answer back, marked with Idempotent-Replayed: true, and nothing is sent or added twice. The same key with a different body gets a 409 with idempotency_conflict, because that is almost always a bug in the caller. Keys are at most 256 characters and are scoped to the API key that sent them.

Idempotency keys work on POST /emails, POST /emails/batch and POST /newsletter/contacts.

Response headers

Finding a call again

Every response carries X-Reggio-Request-Id, and every error repeats it as error.request_id. Keep it in your logs.

Paste one into the API log in the dashboard and you get that call back: the address you called, the status we answered with, and the fields we could not accept. It works for calls that never became a message, which is exactly when you need it. We keep this for 30 days. We never keep request bodies, attachments or keys in it.

If you contact support about a call, quoting the request id is the fastest way for us to find it.

Versioning

Everything in these docs is under /api/v1. Within v1:

• we can add endpoints, optional request fields, response fields, headers, error types and webhook event types;
• we will not remove or rename a field, change its type, or make an optional field required.

Write code that ignores fields it does not recognise and treats an unknown error type like a generic failure for its status code. A change that would break that code ships under a new version instead. Anything an integration would notice is in the changelog.