Lists

Lists group Contacts for campaign targeting. A contact can belong to any number of lists, and each membership tracks its own per-list opt-out independently of the contact's global status.

All endpoints require an Authorization: Bearer YOUR_API_KEY header.

The list object

{
  "id": "ls_newsletter",
  "name": "Newsletter",
  "description": "Weekly product digest",
  "member_count": 1280,
  "created_at": "2026-01-15T10:30:00Z"
}

Field	Type	Description
`id`	string	Unique list identifier.
`name`	string	List name (unique per account among live lists).
`description`	string \| null	Optional description.
`member_count`	number	Count of subscribed (non-opted-out) members.
`created_at`	string	ISO 8601 creation timestamp.

List all lists

GET /v1/lists

Returns every live list with its member count.

{ "lists": [ /* list objects */ ] }

curl "https://api.envloped.com/v1/lists" \
  -H "Authorization: Bearer en_abc123..."

Create a list

POST /v1/lists

Request body

Parameter	Type	Required	Description
`name`	string	Yes	List name (unique per account).
`description`	string	No	Optional description.

Response — `201 Created`

{ "list": { /* list object */ } }

curl -X POST https://api.envloped.com/v1/lists \
  -H "Authorization: Bearer en_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Newsletter", "description": "Weekly product digest" }'

Errors

Status	`error`	Meaning
`400`	`name is required`	The `name` field was missing or empty.
`409`	`duplicate_list`	A live list with this name already exists.

Retrieve a list

GET /v1/lists/:id

{ "list": { /* list object */ } }

Returns 404 if the id is unknown or the list has been deleted.

Update a list

PATCH /v1/lists/:id

Rename or re-describe a list. Only supplied fields change.

Parameter	Type	Description
`name`	string	New name (must stay unique).
`description`	string \| null	New description (`null` clears it).

curl -X PATCH https://api.envloped.com/v1/lists/ls_newsletter \
  -H "Authorization: Bearer en_abc123..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Weekly Newsletter" }'

A name collision returns 409 with { "error": "duplicate_list" }.

Delete a list

DELETE /v1/lists/:id

Soft delete. The list is marked deleted and stops applying to campaign targeting, but the contacts themselves are untouched — they remain in your audience and on any other lists.

{ "deleted": true, "id": "ls_newsletter" }

Membership

List members

GET /v1/lists/:id/contacts

Returns a paginated page of the list's members. Each contact carries two extra membership fields: joined_at and list_unsubscribed_at (the per-list opt-out timestamp, or null).

Query parameter	Type	Description
`page`	number	1-based page number (default `1`).
`limit`	number	Page size, 1–100 (default `50`).

{
  "contacts": [
    {
      "id": "ct_abc123",
      "email": "jane@example.com",
      "status": "subscribed",
      "joined_at": "2026-01-15T10:30:00Z",
      "list_unsubscribed_at": null
    }
  ],
  "total": 1280,
  "page": 1,
  "totalPages": 26
}

Add members

POST /v1/lists/:id/contacts

Adds one or more existing contacts to the list. Send either contact_id (single) or contact_ids (array, max 1000). Only contacts owned by your account are eligible; unknown ids are returned in invalid. Adding a contact that is already a member is a no-op and does not clear a prior per-list opt-out.

{ "contact_ids": ["ct_abc123", "ct_def456"] }

Response:

{ "added": ["ct_abc123", "ct_def456"], "invalid": [] }

Remove members

DELETE /v1/lists/:id/contacts

Removes membership rows (the contacts themselves are not deleted). Send contact_id or contact_ids in the request body.

{ "removed": ["ct_def456"] }

SDKs & CLI

// JavaScript / TypeScript
const list = await client.lists.create({ name: 'Newsletter' });
await client.lists.addContacts(list.id, ['ct_abc123']);

// Go
list, _ := client.Lists.Create(&envloped.CreateListRequest{Name: "Newsletter"})
client.Lists.AddContacts(list.List.ID, []string{"ct_abc123"})

# CLI
envloped lists create "Newsletter"
envloped lists add ls_newsletter ct_abc123 ct_def456
envloped lists members ls_newsletter

Lists

On this page