Lists

Lists are collections of contacts within a project. Use lists to organize subscribers for different campaigns or purposes.

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

Retrieve all lists for a project.

Parameters

Name Type Required Description
project_id integer Yes The project ID

Success response (200) 

client.lists(project_id: 1)
# => {
#   "data" => [
#     {
#       "id" => 1,
#       "project_id" => 1,
#       "name" => "Newsletter",
#       "description" => "Monthly newsletter",
#       "contacts_count" => 50,
#       "subscriber_count" => 48,
#       "unsubscribe_count" => 2,
#       "created_at" => "2024-01-01T00:00:00Z",
#       "updated_at" => "2024-01-01T00:00:00Z"
#     }
#   ],
#   "meta" => {
#     "total" => 1
#   }
# }
GET /api/v1/projects/:project_id/lists/:id

Retrieve a specific list by ID.

Parameters

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

Success response (200) 

client.list(project_id: 1, id: 1)
POST /api/v1/projects/:project_id/lists

Create a new list within a project.

Parameters

Name Type Required Description
project_id integer Yes The project ID

Request body

client.create_list(
  project_id: 1,
  name: 'Newsletter',
  description: 'Monthly newsletter'
)

Success response (201) 

{
  "data" => {
    "id" => 1,
    "project_id" => 1,
    "name" => "Newsletter",
    "description" => "Monthly newsletter",
    "contacts_count" => 0,
    "subscriber_count" => 0,
    "unsubscribe_count" => 0,
    "created_at" => "2024-01-01T00:00:00Z",
    "updated_at" => "2024-01-01T00:00:00Z"
  }
}

Error responses

Status: 422 - validation_error 

{
  "error" => {
    "code" => "validation_error",
    "message" => "Validation failed",
    "details" => {
      "name" => ["can't be blank"]
    }
  }
}
PATCH /api/v1/projects/:project_id/lists/:id

Update an existing list.

Parameters

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

Request body

client.update_list(
  project_id: 1,
  id: 1,
  name: 'Updated Newsletter',
  description: 'Updated description'
)

Success response (200) 

{
  "data" => {
    "id" => 1,
    "project_id" => 1,
    "name" => "Updated Newsletter",
    "description" => "Updated description",
    "contacts_count" => 50,
    "subscriber_count" => 48,
    "unsubscribe_count" => 2,
    "created_at" => "2024-01-01T00:00:00Z",
    "updated_at" => "2024-01-02T00:00:00Z"
  }
}
DELETE /api/v1/projects/:project_id/lists/:id

Delete a list. This will remove all list memberships but will not delete the contacts themselves.

Parameters

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

Success response (204) 

# No content