Create a broadcast

POST

/broadcasts

curl --request POST \
  --url https://api.spacepost.dev/broadcasts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "audience_id": "0198a1c2-7b3e-7a41-9d52-5f6c1e0b8a11", "from": "Acme <news@acme.com>", "subject": "October update", "html": "<p>Hi {{{FIRST_NAME}}}, here is what is new.</p><p><a href=\"{{{RESEND_UNSUBSCRIBE_URL}}}\">Unsubscribe</a></p>" }'

• Production

Creates a draft. The from address must belong to a verified domain of your team and audience_id to one of your audiences.

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

object

audience_id

required

string format: uuid

from

required

An email address, optionally with a display name: Acme <hello@acme.com>.

string

subject

required

string

>= 1 characters <= 998 characters

reply_to

One of:

string

An email address, optionally with a display name: Acme <hello@acme.com>.

string

Array<string>

Array<string>

>= 1 items <= 50 items

preview_text

string

<= 200 characters

html

string

text

string

name

Internal name

string

<= 100 characters

Example

{
  "audience_id": "0198a1c2-7b3e-7a41-9d52-5f6c1e0b8a11",
  "from": "Acme <news@acme.com>",
  "subject": "October update",
  "html": "<p>Hi {{{FIRST_NAME}}}, here is what is new.</p><p><a href=\"{{{RESEND_UNSUBSCRIBE_URL}}}\">Unsubscribe</a></p>"
}

Responses

200

The draft was created.

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

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.