Errors

The API uses HTTP status codes and returns the same JSON body for every error. Read the name in your code and show the message to people.

Error Body

{
  "name": "validation_error",
  "status": 400,
  "message": "Either html or text is required",
  "errors": [
    { "message": "Either html or text is required", "location": "html" }
  ],
  "request_id": "…"
}

A validation error lists each problem in errors. The location is a dot path to the field, such as attachments.0.filename.

Status Codes

Status	Name	Cause
400	validation_error, bad_request	The request is not valid.
401	unauthorized	The API key is missing, wrong, expired or revoked.
403	forbidden	The key cannot do this, or sending is paused.
404	not_found	The resource does not exist.
409	conflict	The resource is in the wrong state, such as a sent email.
429	rate_limit_exceeded	Too many requests, or the daily limit is reached.
500	internal_server_error	Something went wrong on our side.

Rate Limits

Each response carries ratelimit-limit, ratelimit-remaining and ratelimit-reset. A 429 also carries retry-after, the number of seconds to wait before you try again.

Idempotency

Routes that change data take an optional Idempotency-Key header of 1 to 256 printable ASCII characters. A retry with the same key and request returns the first response with Idempotent-Replayed: true, so the email is sent only once.

curl -X POST https://api.inboxjot.com/v1/emails \
  -H "Authorization: Bearer $INBOXJOT_API_KEY" \
  -H "Idempotency-Key: order-1042-receipt" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Status	Name	Cause
400	invalid_idempotency_key	The key is empty, too long or not printable ASCII.
409	concurrent_idempotent_requests	A request with this key is still running. Retry after 1 second.
422	invalid_idempotent_request	The key was already used with a different request.

Keys last 24 hours. Only a 2xx response is stored, so after an error you can fix the request and retry with the same key.