Check a broadcast before sending

GET

/broadcasts/{id}/readiness

curl --request GET \
  --url https://api.spacepost.dev/broadcasts/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/readiness \
  --header 'Authorization: Bearer <token>'

• Production

SpacePost extension (not part of Resend). Returns a deliverability checklist: sender domain and DMARC, subject, Gmail clipping (HTML over 102 KB), image-heavy bodies, link shorteners, spam phrases, unsubscribe link and audience quality. ready is false when any check has level error; POST /broadcasts/{id}/send is then refused with validation_error. Warnings never block a send.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Responses

200

The checklist.

Media typeapplication/json

object

ready

required

boolean

checks

required

Array<object>

object

id

required

string

level

required

string

Allowed values: error warn ok

title

required

string

detail

required

string

code

Stable identifier of the exact message, for localizing it client-side.

string

params

Values interpolated into title and detail.

object

key

additional properties

any

Example

{
  "ready": true,
  "checks": [
    {
      "id": "sender_domain",
      "level": "ok",
      "title": "Sender domain verified",
      "detail": "acme.com is verified."
    },
    {
      "id": "html_size",
      "level": "warn",
      "title": "Gmail will clip this message",
      "detail": "The HTML is 140 KB; Gmail clips messages over 102 KB and hides the rest, including the unsubscribe footer."
    }
  ]
}

401

An error. Common statuses: 400 invalid_idempotency_key; 401 missing_api_key or restricted_api_key; 403 invalid_api_key, invalid_from_address, sending_paused (team or tenant) or invalid_access; 404 not_found; 409 invalid_idempotent_request or concurrent_idempotent_requests; 422 validation_error (also: tenant_id conflicts with the domain’s tenant; deleting a tenant that still has domains); 429 quota errors.

Media typeapplication/json

object

statusCode

required

integer

name

required

Machine-readable error name.

• missing_api_key (401): no bearer token.
• invalid_api_key (403): unknown or malformed key.
• restricted_api_key (401): the key is sending_access (or limited to another domain).
• validation_error (422): invalid request. Also used with 403 for plan limits and test-domain restrictions.
• not_found (404): the resource does not exist or belongs to another team.
• method_not_allowed (405)
• invalid_idempotency_key (400): key length outside 1 to 256.
• concurrent_idempotent_requests (409): the original request is still running.
• invalid_idempotent_request (409): the key was used with a different payload.
• rate_limit_exceeded (429)
• daily_quota_exceeded (429): the sandbox, daily limit or a tenant’s daily_limit was reached.
• monthly_quota_exceeded (429): the plan’s monthly limit was reached (Free plan).
• invalid_from_address (403): the sender domain is not verified.
• invalid_access (422; 403 when a team that is not trusted tries to unpause a tenant paused for its bounce or complaint rate)
• invalid_parameter (422)
• sending_paused (403): sending is paused for the team, or for the tenant named by tenant_id, after a bounce or complaint spike or a manual pause.
• security_error (451)
• application_error (500)
• internal_server_error (500)

string

Allowed values: missing_api_key invalid_api_key restricted_api_key validation_error not_found method_not_allowed invalid_idempotency_key concurrent_idempotent_requests invalid_idempotent_request rate_limit_exceeded daily_quota_exceeded monthly_quota_exceeded invalid_from_address invalid_access invalid_parameter sending_paused security_error application_error internal_server_error

message

required

string

Examples

{
  "statusCode": 422,
  "name": "validation_error",
  "message": "`subject`: Invalid input: expected string, received undefined"
}

{
  "statusCode": 404,
  "name": "not_found",
  "message": "Email not found"
}

{
  "statusCode": 401,
  "name": "missing_api_key",
  "message": "Missing API key in the authorization header. Include `Authorization: Bearer sp_live_...`."
}

403

An error. Common statuses: 400 invalid_idempotency_key; 401 missing_api_key or restricted_api_key; 403 invalid_api_key, invalid_from_address, sending_paused (team or tenant) or invalid_access; 404 not_found; 409 invalid_idempotent_request or concurrent_idempotent_requests; 422 validation_error (also: tenant_id conflicts with the domain’s tenant; deleting a tenant that still has domains); 429 quota errors.

Media typeapplication/json

object

statusCode

required

integer

name

required

Machine-readable error name.

• missing_api_key (401): no bearer token.
• invalid_api_key (403): unknown or malformed key.
• restricted_api_key (401): the key is sending_access (or limited to another domain).
• validation_error (422): invalid request. Also used with 403 for plan limits and test-domain restrictions.
• not_found (404): the resource does not exist or belongs to another team.
• method_not_allowed (405)
• invalid_idempotency_key (400): key length outside 1 to 256.
• concurrent_idempotent_requests (409): the original request is still running.
• invalid_idempotent_request (409): the key was used with a different payload.
• rate_limit_exceeded (429)
• daily_quota_exceeded (429): the sandbox, daily limit or a tenant’s daily_limit was reached.
• monthly_quota_exceeded (429): the plan’s monthly limit was reached (Free plan).
• invalid_from_address (403): the sender domain is not verified.
• invalid_access (422; 403 when a team that is not trusted tries to unpause a tenant paused for its bounce or complaint rate)
• invalid_parameter (422)
• sending_paused (403): sending is paused for the team, or for the tenant named by tenant_id, after a bounce or complaint spike or a manual pause.
• security_error (451)
• application_error (500)
• internal_server_error (500)

string

Allowed values: missing_api_key invalid_api_key restricted_api_key validation_error not_found method_not_allowed invalid_idempotency_key concurrent_idempotent_requests invalid_idempotent_request rate_limit_exceeded daily_quota_exceeded monthly_quota_exceeded invalid_from_address invalid_access invalid_parameter sending_paused security_error application_error internal_server_error

message

required

string

Examples

{
  "statusCode": 422,
  "name": "validation_error",
  "message": "`subject`: Invalid input: expected string, received undefined"
}

{
  "statusCode": 404,
  "name": "not_found",
  "message": "Email not found"
}

{
  "statusCode": 401,
  "name": "missing_api_key",
  "message": "Missing API key in the authorization header. Include `Authorization: Bearer sp_live_...`."
}

404

An error. Common statuses: 400 invalid_idempotency_key; 401 missing_api_key or restricted_api_key; 403 invalid_api_key, invalid_from_address, sending_paused (team or tenant) or invalid_access; 404 not_found; 409 invalid_idempotent_request or concurrent_idempotent_requests; 422 validation_error (also: tenant_id conflicts with the domain’s tenant; deleting a tenant that still has domains); 429 quota errors.

Media typeapplication/json

object

statusCode

required

integer

name

required

Machine-readable error name.

• missing_api_key (401): no bearer token.
• invalid_api_key (403): unknown or malformed key.
• restricted_api_key (401): the key is sending_access (or limited to another domain).
• validation_error (422): invalid request. Also used with 403 for plan limits and test-domain restrictions.
• not_found (404): the resource does not exist or belongs to another team.
• method_not_allowed (405)
• invalid_idempotency_key (400): key length outside 1 to 256.
• concurrent_idempotent_requests (409): the original request is still running.
• invalid_idempotent_request (409): the key was used with a different payload.
• rate_limit_exceeded (429)
• daily_quota_exceeded (429): the sandbox, daily limit or a tenant’s daily_limit was reached.
• monthly_quota_exceeded (429): the plan’s monthly limit was reached (Free plan).
• invalid_from_address (403): the sender domain is not verified.
• invalid_access (422; 403 when a team that is not trusted tries to unpause a tenant paused for its bounce or complaint rate)
• invalid_parameter (422)
• sending_paused (403): sending is paused for the team, or for the tenant named by tenant_id, after a bounce or complaint spike or a manual pause.
• security_error (451)
• application_error (500)
• internal_server_error (500)

string

Allowed values: missing_api_key invalid_api_key restricted_api_key validation_error not_found method_not_allowed invalid_idempotency_key concurrent_idempotent_requests invalid_idempotent_request rate_limit_exceeded daily_quota_exceeded monthly_quota_exceeded invalid_from_address invalid_access invalid_parameter sending_paused security_error application_error internal_server_error

message

required

string

Examples

{
  "statusCode": 422,
  "name": "validation_error",
  "message": "`subject`: Invalid input: expected string, received undefined"
}

{
  "statusCode": 404,
  "name": "not_found",
  "message": "Email not found"
}

{
  "statusCode": 401,
  "name": "missing_api_key",
  "message": "Missing API key in the authorization header. Include `Authorization: Bearer sp_live_...`."
}

429

Too many requests (rate_limit_exceeded), or a daily or monthly sending quota was reached (daily_quota_exceeded also means a tenant’s daily_limit).

Media typeapplication/json

object

statusCode

required

integer

name

required

Machine-readable error name.

• missing_api_key (401): no bearer token.
• invalid_api_key (403): unknown or malformed key.
• restricted_api_key (401): the key is sending_access (or limited to another domain).
• validation_error (422): invalid request. Also used with 403 for plan limits and test-domain restrictions.
• not_found (404): the resource does not exist or belongs to another team.
• method_not_allowed (405)
• invalid_idempotency_key (400): key length outside 1 to 256.
• concurrent_idempotent_requests (409): the original request is still running.
• invalid_idempotent_request (409): the key was used with a different payload.
• rate_limit_exceeded (429)
• daily_quota_exceeded (429): the sandbox, daily limit or a tenant’s daily_limit was reached.
• monthly_quota_exceeded (429): the plan’s monthly limit was reached (Free plan).
• invalid_from_address (403): the sender domain is not verified.
• invalid_access (422; 403 when a team that is not trusted tries to unpause a tenant paused for its bounce or complaint rate)
• invalid_parameter (422)
• sending_paused (403): sending is paused for the team, or for the tenant named by tenant_id, after a bounce or complaint spike or a manual pause.
• security_error (451)
• application_error (500)
• internal_server_error (500)

string

Allowed values: missing_api_key invalid_api_key restricted_api_key validation_error not_found method_not_allowed invalid_idempotency_key concurrent_idempotent_requests invalid_idempotent_request rate_limit_exceeded daily_quota_exceeded monthly_quota_exceeded invalid_from_address invalid_access invalid_parameter sending_paused security_error application_error internal_server_error

message

required

string

Example

{
  "statusCode": 429,
  "name": "rate_limit_exceeded",
  "message": "Too many requests. You can only make 10 requests per second."
}

Headers

retry-after

integer

Seconds to wait before retrying.

ratelimit-limit

integer

Requests allowed per second for your team.

ratelimit-remaining

integer

Requests left in the current one-second window.

ratelimit-reset

integer

Seconds until the window resets.