Send or schedule a broadcast

POST

/broadcasts/{id}/send

curl --request POST \
  --url https://api.spacepost.dev/broadcasts/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "scheduled_at": "2026-10-30T09:00:00Z" }'

• Production

Queues a draft for delivery to every subscribed contact of its audience. The broadcast needs html or text. Without scheduled_at it starts immediately; the status becomes queued, then sending and sent.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Request Body

Media typeapplication/json

object

scheduled_at

ISO 8601 date-time or natural language such as “in 1 hour” or “in 2 days”. At most 30 days ahead.

string

Example

{
  "scheduled_at": "2026-10-30T09:00:00Z"
}

Responses

200

Queued.

Media typeapplication/json

object

id

required

string format: uuid

Example ^generated

{
  "id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0"
}

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_...`."
}

422

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.