Skip to content
spacepostdocs

List audiences

GET
/audiences
curl --request GET \
  --url 'https://api.spacepost.dev/audiences?limit=20' \
  --header 'Authorization: Bearer <token>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 20 >= 1 <= 100

Number of items to return.

after
string format: uuid

Return items older than this id (next page). Cannot be combined with before.

before
string format: uuid

Return items newer than this id (previous page). Cannot be combined with after.

Responses

Section titled “Responses”

200

Section titled “200”

A page of audiences.

Media typeapplication/json
object
object
required
string
Allowed value: list
has_more
required
boolean
data
required
Array<object>
object
object
required
string
Allowed value: audience
id
required
string format: uuid
name
required
string
created_at
required
string format: date-time

Example 

{
  "object": "list",
  "data": [
    {
      "object": "audience"
    }
  ]
}

401

Section titled “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"
}

429

Section titled “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

Section titled “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.