Clusters

A cluster represents a logical grouping of outreach mailboxes that share the same origin IP address. Clusters help improve deliverability by isolating mailbox groups under a single IP, ensuring consistent sending behavior and preventing resource sharing with other users on the platform. Each cluster acts as a micro-server, optimized for outreach performance across a specific team, domain, or campaign strategy.

The cluster model

The cluster model contains all the information about a logical group of outreach mailboxes that are assigned to the same dedicated IP address. Each cluster includes a name and description, an associated count of linked mailboxes or other resources, and metadata such as creation and last updated timestamps. Clusters are used to isolate traffic, improve outreach performance, and prevent shared resource usage across different users or teams on the platform.

Properties

Name
clusterId
Type
string
Description
Unique identifier for the cluster.
Name
workspaceId
Type
string
Description
Unique identifier for the workspace that the cluster belongs to.
Name
clusterName
Type
string
Description
Display name of the cluster, used for organizing and identifying groups of mailboxes.
Name
clusterDescription
Type
string
Description
Optional description providing additional context or purpose of the cluster.
Name
createdAt
Type
timestamp (ISO string)
Description
Timestamp of when the cluster was created.
Name
lastUpdatedAt
Type
timestamp (ISO String)
Description
Timestamp of when the cluster was last updated.

POST/clusters/ListClusters

List all clusters

This endpoint allows you to retrieve a paginated list of all clusters within a workspace. Clusters group mailboxes under the same IP address to optimize deliverability and isolate sending behavior across users or teams.

Required attributes

Name
userId
Type
string
Description
Unique identifier for the user making the request.
Name
workspaceId
Type
string
Description
Unique identifier for the workspace whose clusters should be listed.

Optional attributes

Name
nextToken
Type
string
Description
Token used to paginate through large sets of clusters. Pass the token from a previous response to fetch the next page.
Name
maxItems
Type
integer
Description
Limit the number of clusters returned in the response.

Request

POST

/clusters/ListClusters

curl -X POST https://api.luella.ai/clusters/ListClusters \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "userId": "user_123",
    "workspaceId": "workspace_456",
    "maxItems": 10
  }'

Response

{
  "clusters": [
    {
      "clusterId": "cluster_abc123",
      "clusterName": "Outreach Pool A",
      "associatedCount": 5,
      "createdAt": "2024-03-25T15:32:10.123Z"
    },
    {
      "clusterId": "cluster_xyz789",
      "clusterName": "Warmup Group",
      "associatedCount": 2,
      "createdAt": "2024-04-01T09:17:45.987Z"
    }
  ],
  "nextToken": null
}

POST/clusters/CreateCluster

Create a cluster

This endpoint allows you to create a new cluster within a workspace. A userId, workspaceId and clusterName are required to create a new cluster.

Required attributes

Name
userId
Type
string
Description
Unique identifier for the user creating the cluster.
Name
workspaceId
Type
string
Description
Unique identifier for the workspace the cluster should belong to.
Name
clusterName
Type
string
Description
Display name for the cluster.

Optional attributes

Name
clusterDescription
Type
string
Description
Optional description of what this cluster represents.

Request

POST

/clusters/CreateCluster

curl -X POST https://api.luella.ai/clusters/CreateCluster \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "userId": "user_123",
    "workspaceId": "workspace_456",
    "clusterName": "Outreach Cluster A",
    "clusterDescription": "Handles all US-based outreach accounts."
  }'

Response

{
  "workspaceId": "workspace_456",
  "clusterId": "cluster_abc123"
}

POST/clusters/GetCluster

Retrieve a cluster

This endpoint allows you to retrieve detailed information about a specific cluster, including its name, description, and other metadata.

Required attributes

Name
userId
Type
string
Description
Unique identifier for the user making the request.
Name
workspaceId
Type
string
Description
Unique identifier for the workspace the cluster belongs to.
Name
clusterId
Type
string
Description
Unique identifier for the cluster being fetched.

Request

POST

/clusters/GetCluster

curl -X POST https://api.luella.ai/clusters/GetCluster \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-d '{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "clusterId": "cluster_abc123"
}'

Response

{
  "workspaceId": "workspace_456",
  "clusterId": "cluster_abc123",
  "clusterName": "Outreach Pool A",
  "clusterDescription": "Handles all US mailboxes",
  "associatedCount": 5,
  "createdAt": "2024-03-25T15:32:10.123Z",
  "lastUpdatedAt": "2024-04-01T11:02:58.764Z"
}

POST/clusters/UpdateCluster

Update a cluster

This endpoint allows you to update the name or description of an existing cluster.

Required attributes

Name
userId
Type
string
Description
Unique identifier for the user making the request.
Name
workspaceId
Type
string
Description
Unique identifier for the workspace that the cluster belongs to.
Name
clusterId
Type
string
Description
Unique identifier for the cluster to update.
Name
clusterName
Type
string
Description
New name to assign to the cluster.

Optional attributes

Name
clusterDescription
Type
string
Description
Optional new description for the cluster.

Request

POST

/clusters/UpdateCluster

curl -X POST https://api.luella.ai/clusters/UpdateCluster \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-d '{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "clusterId": "cluster_abc123",
  "clusterName": "New Cluster Name / Old Cluster Name",
  "clusterDescription": "Updated description"
}'

Response

{
  "workspaceId": "workspace_456",
  "clusterId": "cluster_abc123"
}

POST/clusters/DeleteCluster

Delete a cluster

This endpoint allows you to permanently delete a cluster. Deleting a cluster will disassociate any linked mailboxes or resources but will not delete the mailboxes themselves.

Required attributes

Name
userId
Type
string
Description
Unique identifier for the user making the request.
Name
workspaceId
Type
string
Description
Unique identifier for the workspace that the cluster belongs to.
Name
clusterId
Type
string
Description
Unique identifier for the cluster to delete.

Request

POST

/clusters/DeleteCluster

curl -X POST https://api.luella.ai/clusters/DeleteCluster \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "clusterId": "cluster_abc123"
}'