API Reference

Errors

Every error returns a JSON body with statusCode, name, and message.

MailBlastr uses conventional HTTP status codes: 2xx for success, 4xx for problems with the request (a missing field, an invalid key, an unverified domain), and 5xx for server errors. Every error response has the same shape:

{
  "statusCode": 403,
  "name": "invalid_api_key",
  "message": "API key is invalid or has been revoked."
}

Error names

name	Status	Meaning
`invalid_idempotency_key`	400	The `Idempotency-Key` is malformed. It must be between 1 and 256 characters.
`validation_error`	400	One or more fields in the request failed validation. The message details which field and error.
`missing_api_key`	401	No API key in the authorization header. Include `Authorization: Bearer YOUR_API_KEY`.
`restricted_api_key`	401	This API key is restricted to only send emails. Use a key with full access for other actions.
`invalid_api_key`	403	The API key is invalid, expired, or revoked. Generate a new key in the dashboard.
`validation_error`	403	A domain-related rejection — e.g. the `from` domain is not verified, the domain does not match a verified domain, or a domain is already registered.
`not_found`	404	The requested endpoint or resource does not exist (or is not yours).
`invalid_idempotent_request`	409	The same idempotency key was used with a different request payload. Change the key or the payload.
`concurrent_idempotent_requests`	409	The same idempotency key was used while the original request is still in progress. Try again later.
`invalid_attachment`	422	An attachment must have either `content` or `path`.
`invalid_from_address`	422	The `from` field is invalid. Use `email@example.com` or `Name <email@example.com>`.
`invalid_to_address`	422	A recipient address is not a valid email address.
`invalid_access`	422	Access must be `full_access` or `sending_access`. Make sure the key has the necessary permissions.
`missing_required_field`	422	The request body is missing one or more required fields (e.g. `from`, `to`, `subject`).
`daily_quota_exceeded`	429	You have reached your daily email quota. Wait 24 hours or upgrade your plan. Sent and received emails both count.
`monthly_quota_exceeded`	429	You have reached your monthly email quota. Upgrade your plan to increase it. Sent and received emails both count.
`rate_limit_exceeded`	429	Too many requests. Read the rate-limit response headers and reduce your request rate.
`application_error`	500	An unexpected error occurred. Safe to retry idempotent requests later.
`internal_server_error`	500	An unexpected error occurred. Try the request again later.

The same validation_error name is returned with either a 400 (a field failed validation) or a 403 (a domain-related rejection) status, so inspect both statusCode and message.