Lists

Organize subscribers into lists.

GET/api/v1/lists

Retrieve all subscriber lists for your account.

Example

curl https://app.clawdmail.ai/api/v1/lists \
  -H "Authorization: Bearer cm_live_your_key"

Response

{
  "data": {
    "lists": [
      {
        "id": "list_abc123",
        "name": "Newsletter",
        "description": "Weekly product updates",
        "subscriberCount": 1240,
        "createdAt": "2026-01-10T08:00:00Z"
      }
    ]
  }
}

POST/api/v1/lists

Create a new subscriber list.

Parameters

Name	Type	Description
`name`required	string	Display name for the list
`description`	string	Optional description of the list purpose

Example

curl -X POST https://app.clawdmail.ai/api/v1/lists \
  -H "Authorization: Bearer cm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Beta Testers",
    "description": "Users opted into early feature access"
  }'

Response

{
  "data": {
    "id": "list_def456",
    "name": "Beta Testers",
    "description": "Users opted into early feature access",
    "subscriberCount": 0,
    "createdAt": "2026-03-04T12:00:00Z"
  }
}

PATCH/api/v1/lists/:id

Update a list's context. This context is used by ClawdMail's AI when generating emails targeted at this list.

Parameters

Name	Type	Description
`context`required	string	Contextual description of the list audience and purpose — used for AI email generation

Example

curl -X PATCH https://app.clawdmail.ai/api/v1/lists/list_abc123 \
  -H "Authorization: Bearer cm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "context": "Technical audience — senior engineers interested in API updates and infrastructure changes"
  }'

Response

{
  "data": {
    "id": "list_abc123",
    "name": "Newsletter",
    "description": "Weekly product updates",
    "context": "Technical audience — senior engineers interested in API updates and infrastructure changes",
    "subscriberCount": 1240,
    "createdAt": "2026-01-10T08:00:00Z"
  }
}