Retrieve a contact

GET

/audiences/{audienceId}/contacts/{idOrEmail}

curl --request GET \
  --url https://api.spacepost.dev/audiences/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/contacts/jane%40example.com \
  --header 'Authorization: Bearer <token>'

• Production

Authorizations

• bearerAuth

Parameters

Path Parameters

audienceId

required

string format: uuid

idOrEmail

required

string

The contact id or its (URL-encoded) email address.

Example

jane@example.com

Responses

200

The contact.

Media typeapplication/json

object

object

required

string

Allowed value: contact

id

required

string format: uuid

email

required

string format: email

first_name

required

string | null

last_name

required

string | null

created_at

required

string format: date-time

unsubscribed

required

boolean

Example

{
  "object": "contact"
}

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

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.