Lists

A list is a manually membered collection of contacts. The public API can enumerate every list in the workspace and add or remove members on any of them. All four endpoints authenticate with the X-Sender-Tenant + X-API-Key headers and are rooted at https://api.senderz.app/api/v1.

Lists are not segments. A segment computes its own membership from a filter and is a separate resource. Everything on this page operates on lists, whose membership only ever changes when something adds or removes a contact explicitly.

The public API is read plus membership only. There is no endpoint to create, rename, archive or delete a list. Create lists in the dashboard, then manage their members here.

List all lists

GET /api/v1/public/lists

Returns every list in the workspace, newest updated first. There are no filters beyond paging: archived lists are included, so filter on the archived field client side if you need to hide them.

Query parameters

integer

default:"50"

Page size. Must be an integer between 1 and 100.

integer

default:"0"

Number of records to skip. Must be an integer of 0 or more.

The response uses the standard pagination envelope, with a list object per item.

The list object

string

List UUID. Use this as :id on the membership endpoints.

string

Display name.

string

Free-text description. Empty string when none was set, never null.

integer

Cached member count.

string

Hex swatch used in the dashboard. Defaults to #0b1f3f.

boolean

true when the list is archived in the dashboard. Archived lists are still returned by this endpoint and still accept membership changes.

string

Where the members originally came from. One of manual, import, form, api, segment, preference_center. Defaults to manual. This records origin only, it does not restrict what you can do with the list.

object[]

One entry per contact import that landed in this list. Empty array when the list was never imported into.

Show import history entry

string

The import job identifier.

string

ISO 8601 timestamp.

string | null

The user who ran the import, null for a system import.

string

Display label for that actor.

string | null

Uploaded file name, null when the source was not a file.

string

How duplicates were handled: update, skip or add_new.

integer

Contacts created.

integer

Existing contacts updated.

integer

Rows skipped.

integer

Rows rejected as invalid.

integer

Rows in the source file.

Consent page bound to this list, or null.

string | null

ISO 8601 timestamp of the last time members was recounted, or null if it never has been.

string

ISO 8601 creation timestamp.

string

ISO 8601 last-modified timestamp. Results are ordered by this field, newest first.

curl "https://api.senderz.app/api/v1/public/lists?limit=2&offset=0" \
  -H "X-Sender-Tenant: your-workspace-slug" \
  -H "X-API-Key: your-api-key"

const res = await fetch(
  "https://api.senderz.app/api/v1/public/lists?limit=2&offset=0",
  {
    headers: {
      "X-Sender-Tenant": process.env.SENDERZ_WORKSPACE,
      "X-API-Key": process.env.SENDERZ_API_KEY,
    },
  },
);
const { data } = await res.json();
console.log(data.items.map((list) => `${list.name}: ${list.members}`));

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "8f2b1c74-3d5a-4e18-9c60-11a2b3c4d5e6",
        "name": "Newsletter",
        "description": "Weekly roundup subscribers",
        "members": 4218,
        "color": "#0b1f3f",
        "archived": false,
        "source": "form",
        "importHistory": [],
        "consentPageId": null,
        "lastComputedAt": "2026-08-26T09:14:02.417Z",
        "createdAt": "2026-03-04T08:22:10.005Z",
        "updatedAt": "2026-08-26T09:14:02.417Z"
      },
      {
        "id": "c41d9e07-6b28-4a3f-8d15-72e9f0a1b2c3",
        "name": "VIP buyers",
        "description": "",
        "members": 312,
        "color": "#c2410c",
        "archived": false,
        "source": "import",
        "importHistory": [
          {
            "jobId": "imp_7Kq2Xb9",
            "importedAt": "2026-07-18T11:03:44.190Z",
            "actorUserId": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d",
            "actorLabel": "Dana Levi",
            "fileName": "vip-buyers.csv",
            "duplicateMode": "update",
            "imported": 289,
            "updated": 23,
            "skipped": 4,
            "invalid": 1,
            "totalRows": 317
          }
        ],
        "consentPageId": null,
        "lastComputedAt": "2026-08-25T18:40:11.882Z",
        "createdAt": "2026-07-18T10:59:31.774Z",
        "updatedAt": "2026-08-25T18:40:11.882Z"
      }
    ],
    "limit": 2,
    "offset": 0,
    "total": 9,
    "has_more": true,
    "next_cursor": "2"
  }
}

members on this endpoint is the cached count, served without a recount so the listing stays fast. It is refreshed whenever the Lists surface loads a single list, and whenever a membership change goes through the endpoints below. The count returned by an add or remove is always a live count.

Errors

Status	When
`400`	`limit` outside 1 to 100, negative `offset`, a non-integer value, or any unrecognised query parameter.
`401`	Missing or invalid `X-Sender-Tenant` / `X-API-Key`.

Add members

POST /api/v1/public/lists/:id/members

Adds one or more contacts to a list. Returns 201 Created.

string

required

List UUID.

Body

Send at least one of these four fields. They combine: contactId and contactIds are merged with email and emails into a single set of contacts, and duplicates within one request collapse.

string

A single email address. Trimmed and lowercased before lookup.

string[]

Email addresses. Each entry is trimmed and lowercased before lookup.

string

A single contact UUID.

string[]

Contact UUIDs. Entries are validated as UUID v4.

The cap of 100 is a combined total across all four fields, not 100 each. A request whose contactIds plus contactId plus emails plus email exceeds 100 returns 400 with Up to 100 profiles can be changed at once. Either array alone exceeding 100 entries is also rejected at validation.

How addresses resolve

Known email

An address that already belongs to a contact in the workspace resolves to that contact.

Unknown email

A new contact is created with that address and then added to the list. The new contact has no marketing consent recorded, so it is not sendable to until consent is captured. List membership and consent are independent.

Contact IDs

A contactId that does not belong to the workspace, or belongs to a deleted contact, is silently skipped and does not count toward added.

Response

integer

Contacts actually inserted into the list by this call. A contact that was already a member, or a contact ID that did not resolve, counts as 0.

integer

Live total members on the list after the call.

curl -X POST \
  https://api.senderz.app/api/v1/public/lists/c41d9e07-6b28-4a3f-8d15-72e9f0a1b2c3/members \
  -H "X-Sender-Tenant: your-workspace-slug" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": ["dana@example.com", "noa@example.com"],
    "contactId": "0a1b2c3d-4e5f-4a6b-8c7d-8e9f0a1b2c3d"
  }'

const res = await fetch(
  "https://api.senderz.app/api/v1/public/lists/c41d9e07-6b28-4a3f-8d15-72e9f0a1b2c3/members",
  {
    method: "POST",
    headers: {
      "X-Sender-Tenant": process.env.SENDERZ_WORKSPACE,
      "X-API-Key": process.env.SENDERZ_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ emails: ["dana@example.com", "noa@example.com"] }),
  },
);
const { data } = await res.json();

{
  "success": true,
  "data": { "added": 3, "count": 315 }
}

Errors

Status	When
`400`	`:id` is not a UUID, an address fails email validation, a `contactIds` entry is not a UUID v4, the combined member total exceeds 100, or the body carries an unrecognised property.
`400`	`No resolvable contacts to add` when nothing in the body resolved to a contact.
`401`	Missing or invalid `X-Sender-Tenant` / `X-API-Key`.
`404`	`List not found`. The list is loaded and tenant-scoped before any membership write, so an unknown or foreign list ID fails before anything changes.

Remove members by identity

DELETE /api/v1/public/lists/:id/members

Removes one or more contacts from a list by email or by contact ID. Returns 200 OK, not 204.

string

required

List UUID.

Body

The same four fields as the add endpoint, with the same combined cap of 100 and the same trimming and lowercasing of addresses.

string

A single email address.

string[]

Email addresses.

string

A single contact UUID.

string[]

Contact UUIDs. Entries are validated as UUID v4.

Removal never creates anything. An email that matches no contact is simply skipped, in contrast with the add endpoint which creates a contact for it. Contact IDs you supply always count as resolved, so a syntactically valid but unknown UUID passes the guard below and is reported as removed 0.

Response

integer

Contacts actually removed from the list. A contact that was not a member counts as 0.

integer

Live total members on the list after the call.

curl -X DELETE \
  https://api.senderz.app/api/v1/public/lists/c41d9e07-6b28-4a3f-8d15-72e9f0a1b2c3/members \
  -H "X-Sender-Tenant: your-workspace-slug" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{ "email": "dana@example.com" }'

const res = await fetch(
  "https://api.senderz.app/api/v1/public/lists/c41d9e07-6b28-4a3f-8d15-72e9f0a1b2c3/members",
  {
    method: "DELETE",
    headers: {
      "X-Sender-Tenant": process.env.SENDERZ_WORKSPACE,
      "X-API-Key": process.env.SENDERZ_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ email: "dana@example.com" }),
  },
);
const { data } = await res.json();

{
  "success": true,
  "data": { "removed": 1, "count": 314 }
}

Errors

Status	When
`400`	`:id` is not a UUID, an address fails email validation, a `contactIds` entry is not a UUID v4, the combined member total exceeds 100, or the body carries an unrecognised property.
`400`	`No resolvable contacts to remove` when nothing in the body resolved to a contact.
`401`	Missing or invalid `X-Sender-Tenant` / `X-API-Key`.
`404`	`List not found`.

Remove a single member by ID

DELETE /api/v1/public/lists/:id/members/:contactId

Removes one contact from a list. Returns 200 OK.

string

required

List UUID.

string

required

Contact UUID.

There is no request body.

Response

integer

Live total members on the list after the call.

This endpoint is idempotent and does not report whether anything was removed. Removing a contact that was never a member succeeds and returns the unchanged count. Use the identity endpoint above when you need the removed figure.

curl -X DELETE \
  https://api.senderz.app/api/v1/public/lists/c41d9e07-6b28-4a3f-8d15-72e9f0a1b2c3/members/0a1b2c3d-4e5f-4a6b-8c7d-8e9f0a1b2c3d \
  -H "X-Sender-Tenant: your-workspace-slug" \
  -H "X-API-Key: your-api-key"

{
  "success": true,
  "data": { "count": 313 }
}

Errors

Status	When
`400`	`:id` or `:contactId` is not a UUID.
`401`	Missing or invalid `X-Sender-Tenant` / `X-API-Key`.
`404`	`List not found`.

Webhooks

Membership changes made through these endpoints fire outbound webhooks, one event per contact:

Event	Fired when
`list.subscribed`	A contact is added, once per contact in the request.
`list.unsubscribed`	A contact is actually removed. A no-op removal fires nothing.

The payload carries listId, listName and contactId. Dispatch is best effort: a webhook that fails to deliver is logged and does not fail or roll back the membership change.

Bulk membership changes are cheapest in batches of up to 100 identifiers per request. Page through GET /public/lists once to resolve your list IDs and cache them, since list IDs are stable.

Introduction

Ingest & transactional

Public API

List all lists

Query parameters

The list object

Errors

Add members

Body

How addresses resolve

Response

Errors

Remove members by identity

Body

Response

Errors

Remove a single member by ID

Response

Errors

Webhooks

​List all lists

​Query parameters

​The list object

​Errors

​Add members

​Body

​How addresses resolve

​Response

​Errors

​Remove members by identity

​Body

​Response

​Errors

​Remove a single member by ID

​Response

​Errors

​Webhooks

List all lists

Query parameters

The list object

Errors

Add members

Body

How addresses resolve

Response

Errors

Remove members by identity

Body

Response

Errors

Remove a single member by ID

Response

Errors

Webhooks