Projects

Projects are the top-level containers for organizing your email lists and contacts.

GET /api/v1/projects

Retrieve all projects in your environment.

Success response (200) 

client.projects
# => {
#   "data" => [
#     {
#       "id" => 1,
#       "name" => "My Project",
#       "description" => "Project description",
#       "lists_count" => 5,
#       "contacts_count" => 100,
#       "total_subscribers" => 95,
#       "created_at" => "2024-01-01T00:00:00Z",
#       "updated_at" => "2024-01-01T00:00:00Z"
#     }
#   ],
#   "meta" => {
#     "total" => 1
#   }
# }

Error responses

Status: 401 - unauthorized 

{
  "error" => {
    "code" => "unauthorized",
    "message" => "Invalid API key"
  }
}
GET /api/v1/projects/:id

Retrieve a specific project by ID.

Parameters

Name Type Required Description
id integer Yes The project ID

Success response (200) 

client.project(1)
# => {
#   "data" => {
#     "id" => 1,
#     "name" => "My Project",
#     "description" => "Project description",
#     "lists_count" => 5,
#     "contacts_count" => 100,
#     "total_subscribers" => 95,
#     "created_at" => "2024-01-01T00:00:00Z",
#     "updated_at" => "2024-01-01T00:00:00Z"
#   }
# }

Error responses

Status: 404 - not_found 

{
  "error" => {
    "code" => "not_found",
    "message" => "Resource not found"
  }
}
POST /api/v1/projects

Create a new project.

Request body

client.create_project(
  name: 'My New Project',
  description: 'Project description'
)

Success response (201) 

{
  "data" => {
    "id" => 1,
    "name" => "My New Project",
    "description" => "Project description",
    "lists_count" => 0,
    "contacts_count" => 0,
    "total_subscribers" => 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/:id

Update an existing project.

Parameters

Name Type Required Description
id integer Yes The project ID

Request body

client.update_project(1, name: 'Updated Name', description: 'Updated description')

Success response (200) 

{
  "data" => {
    "id" => 1,
    "name" => "Updated Name",
    "description" => "Updated description",
    "lists_count" => 5,
    "contacts_count" => 100,
    "total_subscribers" => 95,
    "created_at" => "2024-01-01T00:00:00Z",
    "updated_at" => "2024-01-02T00:00:00Z"
  }
}

Error responses

Status: 404 - not_found 

{
  "error" => {
    "code" => "not_found",
    "message" => "Resource not found"
  }
}
DELETE /api/v1/projects/:id

Delete a project. This will also delete all associated lists and contacts.

Parameters

Name Type Required Description
id integer Yes The project ID

Success response (204) 

# No content

Error responses

Status: 404 - not_found 

{
  "error" => {
    "code" => "not_found",
    "message" => "Resource not found"
  }
}