Subscribers

Manage your email subscribers.

GET/api/v1/subscribers

Retrieve a paginated list of subscribers. Filter by status or list membership.

Parameters

Name	Type	Description
`status`	string	Filter by status — "active", "unsubscribed", or "bounced"
`listId`	string	Filter to subscribers belonging to a specific list

Example

curl https://app.clawdmail.ai/api/v1/subscribers?status=active \
  -H "Authorization: Bearer cm_live_your_key"

Response

{
  "data": {
    "subscribers": [
      {
        "id": "sub_8f3a1b2c4d5e",
        "email": "jane@example.com",
        "firstName": "Jane",
        "lastName": "Doe",
        "status": "active",
        "createdAt": "2026-01-15T09:30:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 50
  }
}

POST/api/v1/subscribers

Add a single subscriber to your account.

Parameters

Name	Type	Description
`email`required	string	Email address of the subscriber
`firstName`	string	Subscriber first name
`lastName`	string	Subscriber last name

Example

curl -X POST https://app.clawdmail.ai/api/v1/subscribers \
  -H "Authorization: Bearer cm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "firstName": "Jane",
    "lastName": "Doe"
  }'

Response

{
  "data": {
    "id": "sub_9e7d6c5b4a3f",
    "email": "jane@example.com",
    "firstName": "Jane",
    "lastName": "Doe",
    "status": "active",
    "createdAt": "2026-03-04T12:00:00Z"
  }
}

POST/api/v1/subscribers/bulk

Import multiple subscribers in a single request. Each entry is validated individually — partial success is possible.

Parameters

Name	Type	Description
`subscribers`required	array	[{email, firstName?, lastName?}]
`listId`	string	Automatically add imported subscribers to this list

Example

curl -X POST https://app.clawdmail.ai/api/v1/subscribers/bulk \
  -H "Authorization: Bearer cm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "subscribers": [
      { "email": "jane@example.com", "firstName": "Jane" },
      { "email": "alex@example.com", "firstName": "Alex", "lastName": "Smith" }
    ],
    "listId": "list_abc123"
  }'

Response

{
  "data": {
    "created": 2,
    "failed": 0,
    "errors": []
  }
}

PATCH/api/v1/subscribers/:id

Update an existing subscriber. Pass only the fields you want to change.

Parameters

Name	Type	Description
`email`	string	Updated email address
`firstName`	string	Updated first name
`lastName`	string	Updated last name
`status`	string	"active", "unsubscribed", or "bounced"

Example

curl -X PATCH https://app.clawdmail.ai/api/v1/subscribers/sub_9e7d6c5b4a3f \
  -H "Authorization: Bearer cm_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "firstName": "Janet" }'

Response

{
  "data": {
    "id": "sub_9e7d6c5b4a3f",
    "email": "jane@example.com",
    "firstName": "Janet",
    "lastName": "Doe",
    "status": "active",
    "createdAt": "2026-03-04T12:00:00Z"
  }
}

DELETE/api/v1/subscribers/:id

Permanently delete a subscriber and remove them from all lists.

Example

curl -X DELETE https://app.clawdmail.ai/api/v1/subscribers/sub_9e7d6c5b4a3f \
  -H "Authorization: Bearer cm_live_your_key"

Response

{
  "data": {
    "deleted": true
  }
}