Skip to Content
Alienmail Docs

Errors

Status codes and the error format.

Alienmail uses standard HTTP status codes. A 2xx means success. Anything else has a JSON body with an error object:

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid. Check the fields.",
    "fields": { "dailyLimit": "Too big: expected number to be <=2000" }
  }
}
  • code is stable: use it in your code.
  • message is written for people and may change.
  • fields comes with validation errors, including bad query parameters like status or cursor. It maps each field to what is wrong with it. Nested fields use dots (leads.0.firstName, custom.plan), and _ stands for the body as a whole.

Unknown paths under /api/v1 and unsupported methods answer in this format too.

Request bodies

Send bodies as JSON with the header Content-Type: application/json. A body with another content type is refused with 415, and one that isn't valid JSON with 400 and the code invalid_json.

Bodies are checked strictly. A field the endpoint doesn't know is refused with 400 instead of being ignored, so a typo like first_name for firstName can't pass silently:

{
  "error": {
    "code": "bad_request",
    "message": "The request is invalid. Check the fields.",
    "fields": { "leads.0": "Unrecognized key: \"first_name\"" }
  }
}

Status codes

StatusCodeMeaning
200Success.
400bad_requestThe request is invalid. Check fields.
400invalid_jsonThe body isn't valid JSON.
401unauthorizedMissing or invalid API key. See Authentication.
403forbiddenThe key's role lacks the permission the endpoint needs.
404not_foundThe campaign, lead or mailbox doesn't exist in your workspace, or the path isn't an endpoint. An id that isn't a number, or an email that isn't an email address, is a 404 too.
405method_not_allowedThe endpoint doesn't support this method. The Allow header lists the ones it does.
409conflictThe campaign, lead or mailbox is in a state that doesn't allow the request. message says why.
415unsupported_media_typeThe body isn't sent as application/json.
429rate_limitedToo many requests. Wait for Retry-After seconds.
500server_errorSomething went wrong on our side. Retry later.

Conflicts

A 409 means the request was understood but can't be done right now. Common cases:

RequestRefused when
Start a campaignIt is archived, its end date has passed, no email step has content, or no mailbox on it is active and connected.
Pause a campaignIt isn't active.
Add or remove leadsThe campaign is archived.
Update a leadThe campaign is completed or archived, or it is active and the lead has already been emailed.

Retrying

  • 429 and 5xx are safe to retry after a pause. Back off exponentially for 5xx.
  • Don't retry other 4xx responses unchanged: they will fail the same way.
  • Every write in this API is safe to repeat. Adding a lead who is already in the campaign doesn't add them twice, removing one who is gone counts them in notInCampaign, and starting an active campaign or pausing a paused one returns it unchanged. There are no idempotency keys.

On this page