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" }
}
}codeis stable: use it in your code.messageis written for people and may change.fieldscomes with validation errors, including bad query parameters likestatusorcursor. 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
| Status | Code | Meaning |
|---|---|---|
200 | Success. | |
400 | bad_request | The request is invalid. Check fields. |
400 | invalid_json | The body isn't valid JSON. |
401 | unauthorized | Missing or invalid API key. See Authentication. |
403 | forbidden | The key's role lacks the permission the endpoint needs. |
404 | not_found | The 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. |
405 | method_not_allowed | The endpoint doesn't support this method. The Allow header lists the ones it does. |
409 | conflict | The campaign, lead or mailbox is in a state that doesn't allow the request. message says why. |
415 | unsupported_media_type | The body isn't sent as application/json. |
429 | rate_limited | Too many requests. Wait for Retry-After seconds. |
500 | server_error | Something went wrong on our side. Retry later. |
Conflicts
A 409 means the request was understood but can't be done right now. Common cases:
| Request | Refused when |
|---|---|
| Start a campaign | It is archived, its end date has passed, no email step has content, or no mailbox on it is active and connected. |
| Pause a campaign | It isn't active. |
| Add or remove leads | The campaign is archived. |
| Update a lead | The campaign is completed or archived, or it is active and the lead has already been emailed. |
Retrying
429and5xxare safe to retry after a pause. Back off exponentially for5xx.- Don't retry other
4xxresponses 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.