Lists

Mailing lists let you organize subscribers into groups for targeted campaigns. Each subscriber record belongs to one list, but the same email address can have separate records in several lists, and campaigns can target a specific list or segment within a list.

Create a List

POST https://api.mail.land/v1/marketing/lists

Create list request

{
  "name": "Product Updates",
  "description": "Subscribers interested in product announcements"
}

Field	Type	Required	Description
`name`	string	Yes	List name (must be unique per workspace)
`description`	string	No	List description

Create a mailing list

curl -X POST https://api.mail.land/v1/marketing/lists \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Product Updates", "description": "Product announcements" }'

Response

List response

{
  "id": "vtmlew96u277jq",
  "name": "Product Updates",
  "description": "Product announcements",
  "isActive": true,
  "subscriberCount": 0,
  "createdAt": "2026-02-17T12:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

List All Mailing Lists

GET https://api.mail.land/v1/marketing/lists

Parameter	Type	Default	Description
`cursor`	string	-	Opaque cursor from the previous page's `nextCursor`. Omit for the first page.
`limit`	int	20	Items per page
`search`	string	-	Search by name
`isActive`	bool	-	Filter by active status
`sortBy`	string	-	Sort field
`sortDesc`	bool	false	Sort descending

List all mailing lists

curl "https://api.mail.land/v1/marketing/lists?limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

List response

{
  "items": [
    {
      "id": "vtmlew96u277jq",
      "name": "Product Updates",
      "description": "Product announcements",
      "isActive": true,
      "subscriberCount": 2500,
      "createdAt": "2026-01-10T08:00:00Z",
      "updatedAt": "2026-02-17T12:00:00Z"
    }
  ],
  "nextCursor": "eyJ2IjoxLCJzIjoiY3JlYXRlZGF0OmRlc2MiLCJrIjoi...",
  "hasMore": true
}

Get List Details

GET https://api.mail.land/v1/marketing/lists/{id}

Returns extended details including subscriber breakdown:

Get list details

curl https://api.mail.land/v1/marketing/lists/vtmlew96u277jq \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

List detail response

{
  "id": "vtmlew96u277jq",
  "name": "Product Updates",
  "description": "Product announcements",
  "isActive": true,
  "subscriberCount": 2500,
  "activeSubscribers": 2300,
  "unsubscribedCount": 150,
  "bouncedCount": 50,
  "createdAt": "2026-01-10T08:00:00Z",
  "updatedAt": "2026-02-17T12:00:00Z"
}

Update a List

PUT https://api.mail.land/v1/marketing/lists/{id}

Update list request

{
  "name": "Product Announcements",
  "description": "Updated description",
  "isActive": true
}

Field	Type	Required	Description
`name`	string	Yes	List name (must be unique)
`description`	string	No	List description
`isActive`	bool	No	Active status (default: `true`)

isActive is a label only: setting it to false does not block sending. Nothing in the campaign or worker code reads it to prevent a campaign from targeting this list.

Update a mailing list

curl -X PUT https://api.mail.land/v1/marketing/lists/vtmlew96u277jq \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Announcements",
    "description": "Updated description",
    "isActive": true
  }'

Delete a List

DELETE https://api.mail.land/v1/marketing/lists/{id}

Deletes the mailing list. Subscribers in this list are not deleted but their mailingListId is cleared (a SetNull foreign key). List-scoped unsubscribes are preserved when a list is deleted.

If a subscriber in this list already has a contact with no list (for example because they were in another list that was deleted earlier), that contact is kept, and their membership of this list is kept only as history: it no longer appears in contacts, and no campaign or automation targets it. Its unsubscribes, consent records and campaign history are preserved.

Delete a mailing list

curl -X DELETE https://api.mail.land/v1/marketing/lists/vtmlew96u277jq \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Error Responses

Status	Code	Description
`400`	`VALIDATION_FAILED`	Name is required
`400`	`INVALID_REQUEST`	A mailing list with this name already exists
`403`	`FORBIDDEN`	Insufficient permissions
`404`	`RESOURCE_NOT_FOUND`	Mailing list not found

Next Steps

Subscribers: add subscribers to your lists
Segments: create dynamic segments within lists
Campaigns: send campaigns to your lists

Lists

Create a ListCopy Anchor Link

ResponseCopy Anchor Link

List All Mailing ListsCopy Anchor Link

Get List DetailsCopy Anchor Link

Update a ListCopy Anchor Link

Delete a ListCopy Anchor Link

Error ResponsesCopy Anchor Link

Next StepsCopy Anchor Link

On this page