Errors and limits

Every error has the same shape and a stable code you can branch on. Messages are for humans and may change.

JSON

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [{ "field": "from", "issue": "must be a valid email address" }],
    "requestId": "req_7c26…"
  }
}

Quote the requestId (also in the x-request-id header) when contacting support.

Codes

HTTP	Code	Meaning
400	VALIDATION_ERROR	The request is malformed; see details.
401	UNAUTHENTICATED	Missing, invalid or revoked API key.
403	FORBIDDEN	The key lacks permission (e.g. a sending-only key reading emails).
403	DOMAIN_NOT_VERIFIED	Live email from a domain that is not verified in this workspace.
403	WORKSPACE_SUSPENDED	Sending is blocked for this workspace; contact support.
404	NOT_FOUND	The resource does not exist in this workspace.
409	CONFLICT	For example, an Idempotency-Key reused with a different body.
413	PAYLOAD_TOO_LARGE	Body over the limit (15 MB for /v1/emails, 3 MB elsewhere).
429	RATE_LIMITED	Too many requests; wait for Retry-After seconds.
429	QUOTA_EXCEEDED	Monthly or daily email limit of your plan reached.
5xx	INTERNAL_ERROR	Our fault. Safe to retry with the same Idempotency-Key.

Limits

Limit	Value
API requests	Per API key, per second, by plan (2 on Free up to 100 on Enterprise). Shared by every server using the key.
Emails	Per calendar month (UTC) by plan; Free also has 100 per day. Each recipient counts once; test emails do not count.
Recipients per email	50 across to, cc and bcc.
Batch size	100 emails.
Attachments	10 files, 10 MB in total.
Scheduling	Up to 30 days ahead.