Create a contact list

POST/api/v1/contact-lists
Requires anorganization API keywith the scopecontacts:write

Request body

  • namestringrequired

    Its name, shown in the dashboard.

  • descriptionstring

    Optional. A note for your team, shown in the dashboard.

Request

POST/api/v1/contact-lists
curl -X POST 'https://app.mailyte.com/api/v1/contact-lists' \
  -H 'Authorization: Bearer mk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Newsletter subscribers",
    "description": "Opted in via the footer form"
  }'
The key names its own organization, so no X-Organization-ID header is needed.

Response

Success.

  • dataobject
    • objectstringcontact_list
    • idstring

      Unique identifier for the list.

    • namestring
    • descriptionstring

      Your note on what the list is for. Null when none was written.

    • contact_countinteger

      Every member of the list, including unsubscribed ones. For the members who can be emailed, use GET /contacts?list_id=… and filter on state.

    • created_atstring
    • updated_atstring

Returned inside the standard envelope.

Errors

StatusWhen
401The API key is missing, unknown, revoked or expired. All four answer identically, on purpose: distinguishing them would confirm which keys exist.
403The key is valid but may not do this: it lacks the required scope, its IP allowlist does not include you, or this endpoint does not accept API keys.
404No such resource in this organization.
422The request was understood but the values were not acceptable.
429Too many requests, or the organization has spent its sending allowance. `Retry-After` says how long to wait.

Every status, with what causes it and what to do, is on the error reference.