Lists

Static lists (managed by explicit membership) and dynamic lists (membership computed from a segment).

Create a list

Creates a static list, or a dynamic list backed by a segment when `type` is `dynamic`. Pass `property_ids` to assign the properties shown and collected for its contacts, in column order.

POST

/lists

Authorizations

Authorization

string

header

required

API key for your workspace, scoped to contacts:manage. Pass it as a Bearer token in the Authorization header.

Body · application/json

name

string

type

string

property_ids

number[]

Create a list

curl https://api.mailcraft.host/v1/lists \
  -X POST \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{ "name": "Newsletter", "type": "static", "property_ids": [3, 7] }'

{
  "data": {
    "id": 4,
    "name": "Newsletter",
    "description": null,
    "type": "static",
    "segment_id": null,
    "properties": [
      { "id": 3, "key": "plan", "label": "Plan", "type": "text" },
      { "id": 7, "key": "seats", "label": "Seats", "type": "number" }
    ],
    "created_at": "2026-09-22T14:07:00.000000Z"
  }
}

List all lists

Returns every list in the workspace, both static and dynamic.

GET

/lists

Authorizations

Authorization

string

header

required

API key for your workspace, scoped to contacts:manage. Pass it as a Bearer token in the Authorization header.

List all lists

curl https://api.mailcraft.host/v1/lists \
  -H 'Authorization: Bearer sk_live_...'

{
  "data": [
    {
      "id": 4,
      "name": "Newsletter",
      "type": "static",
      "segment_id": null,
      "properties": [{ "id": 3, "key": "plan", "label": "Plan", "type": "text" }]
    }
  ]
}

Get a list

Fetches a single list by id.

GET

/lists/{list}

Authorizations

Authorization

string

header

required

API key for your workspace, scoped to contacts:manage. Pass it as a Bearer token in the Authorization header.

Get a list

curl https://api.mailcraft.host/v1/lists/4 \
  -H 'Authorization: Bearer sk_live_...'

{
  "data": {
    "id": 4,
    "name": "Newsletter",
    "description": null,
    "type": "static",
    "segment_id": null,
    "properties": [
      { "id": 3, "key": "plan", "label": "Plan", "type": "text" },
      { "id": 7, "key": "seats", "label": "Seats", "type": "number" }
    ],
    "created_at": "2026-09-22T14:07:00.000000Z"
  }
}

Set list properties

Replaces the properties assigned to the list, in column order. They are shown as columns for its contacts and collected when adding one. Values live on the contact, so they are shared with other lists. Send an empty array to clear them.

PUT

/lists/{list}/properties

Authorizations

Authorization

string

header

required

API key for your workspace, scoped to contacts:manage. Pass it as a Bearer token in the Authorization header.

Body · application/json

property_ids

number[]

Set list properties

curl https://api.mailcraft.host/v1/lists/4/properties \
  -X PUT \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{ "property_ids": [7, 3] }'

{
  "data": {
    "id": 4,
    "name": "Newsletter",
    "type": "static",
    "properties": [
      { "id": 7, "key": "seats", "label": "Seats", "type": "number" },
      { "id": 3, "key": "plan", "label": "Plan", "type": "text" }
    ]
  }
}

List contacts on a list

Returns the contacts on the list, newest first, cursor-paginated (`limit`, `cursor`). For a dynamic list these are the contacts currently matching its segment.

GET

/lists/{list}/contacts

Authorizations

Authorization

string

header

required

API key for your workspace, scoped to contacts:manage. Pass it as a Bearer token in the Authorization header.

List contacts on a list

curl 'https://api.mailcraft.host/v1/lists/4/contacts?limit=50' \
  -H 'Authorization: Bearer sk_live_...'

{
  "data": [
    {
      "id": "01J9ZQ7K3M5N8P2R4T6V8X0Y1Z",
      "email": "[email protected]",
      "first_name": "Ada",
      "last_name": null,
      "status": "subscribed",
      "properties": { "plan": "pro", "seats": 12 }
    }
  ],
  "links": { "next": null },
  "meta": { "per_page": 50, "next_cursor": null }
}

Add a contact to a list

Adds a contact to a static list, creating it if the email is new or updating it if not. `properties` values must match each property's type; `null` clears a value. Returns 201 for a new contact and 200 for an existing one. Joining can start automations triggered by this list.

POST

/lists/{list}/contacts

Authorizations

Authorization

string

header

required

API key for your workspace, scoped to contacts:manage. Pass it as a Bearer token in the Authorization header.

Body · application/json

email

string

first_name

string

properties

object

Add a contact to a list

curl https://api.mailcraft.host/v1/lists/4/contacts \
  -X POST \
  -H 'Authorization: Bearer sk_live_...' \
  -H 'Content-Type: application/json' \
  -d '{ "email": "[email protected]", "first_name": "Ada", "properties": { "plan": "pro", "seats": 12 } }'

{
  "data": {
    "id": "01J9ZQ7K3M5N8P2R4T6V8X0Y1Z",
    "email": "[email protected]",
    "first_name": "Ada",
    "last_name": null,
    "status": "subscribed",
    "properties": { "plan": "pro", "seats": 12 },
    "created_at": "2026-09-24T09:12:00.000000Z"
  }
}

Delete a list

Deletes the list. Contacts on it are not deleted, only their membership in this list.

DELETE

/lists/{list}

Authorizations

Authorization

string

header

required

API key for your workspace, scoped to contacts:manage. Pass it as a Bearer token in the Authorization header.

Delete a list

curl https://api.mailcraft.host/v1/lists/4 \
  -X DELETE \
  -H 'Authorization: Bearer sk_live_...'

(empty body)