List contacts

Manage which contacts belong to which lists. Contacts can be members of multiple lists.

Unsubscribe URLs

All list contact responses include an unsubscribe_url field for each contact. This URL is specific to the list and contact combination. Include this URL in your email templates to provide recipients with unsubscribe functionality.

GET /api/v1/projects/:project_id/lists/:list_id/contacts

Retrieve all contacts in a specific list. Results are paginated.

Parameters

Name Type Required Description
project_id integer Yes The project ID
list_id integer Yes The list ID
page integer No Page number (default: 1)
per_page integer No Items per page (default: 25)

Success response (200) 

client.list_contacts(project_id: 1, list_id: 1)
# => {
#   "data" => [
#     {
#       "id" => 1,
#       "email" => "user@example.com",
#       "first_name" => "John",
#       "last_name" => "Doe",
#       "created_at" => "2024-01-01T00:00:00Z",
#       "unsubscribe_url" => "https://emaillist.dev/unsubscribe/abc123token..."
#     }
#   ],
#   "meta" => {
#     "page" => 1,
#     "per_page" => 25,
#     "total" => 50,
#     "total_pages" => 2
#   }
# }
POST /api/v1/projects/:project_id/lists/:list_id/contacts

Add one or more contacts to a list. Contacts can be specified by ID or email. Contacts must already exist in the project.

Parameters

Name Type Required Description
project_id integer Yes The project ID
list_id integer Yes The list ID

Request body

client.add_contacts_to_list(
  project_id: 1,
  list_id: 1,
  contacts: [
    { id: 1 },
    { email: 'newuser@example.com' }
  ]
)

Success response (201) 

{
  "data" => {
    "added" => 2,
    "skipped" => 0,
    "contacts" => [
      {
        "id" => 1,
        "email" => "user@example.com",
        "first_name" => "John",
        "last_name" => "Doe",
        "created_at" => "2024-01-01T00:00:00Z",
        "unsubscribe_url" => "https://emaillist.dev/unsubscribe/abc123token..."
      },
      {
        "id" => 2,
        "email" => "newuser@example.com",
        "first_name" => nil,
        "last_name" => nil,
        "created_at" => "2024-01-01T00:00:00Z",
        "unsubscribe_url" => "https://emaillist.dev/unsubscribe/def456token..."
      }
    ],
    "message" => "Added 2 contact(s) to list"
  }
}

Error responses

Status: 400 - missing_parameter 

{
  "error" => {
    "code" => "missing_parameter",
    "message" => "contacts array is required"
  }
}

Status: 400 - validation_error 

{
  "error" => {
    "code" => "validation_error",
    "message" => "No valid contacts found. Provide contacts with 'id' or 'email'"
  }
}

Status: 422 - validation_error 

{
  "error" => {
    "code" => "validation_error",
    "message" => "All contacts are already in this list"
  }
}
DELETE /api/v1/projects/:project_id/lists/:list_id/contacts/:id

Remove a contact from a list. This does not delete the contact, only removes the list membership.

Parameters

Name Type Required Description
project_id integer Yes The project ID
list_id integer Yes The list ID
id integer Yes The contact ID

Success response (204) 

# No content

Error responses

Status: 404 - not_found 

{
  "error" => {
    "code" => "not_found",
    "message" => "Contact is not in this list"
  }
}