API reference

Lists

Static contact lists — curated broadcast audiences and their members.

Auth: Session token · Base URL: https://api.mailkite.dev

Endpoints

Each row expands to its request and response schema. The address bar follows along, so any endpoint can be linked to directly.

GET /api/lists List your contact lists (static, curated broadcast audiences), each with its member count.

List your contact lists (static, curated broadcast audiences), each with its member count.

Response body

array contact-list.json

A named list of contacts (lst_…), used as a broadcast audience. GET /api/lists/:id adds member_count; other responses return the bare row.

Field	Type	Notes
id req	string	List id (lst_…).
user_id req	string	Owning account (usr_…).
name req	string	Display name, unique per account.
member_count	integer	How many contacts the list holds. Detail (GET one) responses only.
created_at req	integer	When the list was created, in Unix epoch milliseconds (UTC).
updated_at req	integer	When the list last changed, in Unix epoch milliseconds (UTC).

An actual array of results, recorded from the conformance suite.

response.json

[
  {
    "id": "lst_5Wd9JqRs",
    "user_id": "usr_7Fj3MnQw",
    "name": "Newsletter",
    "created_at": 1769731200000,
    "updated_at": 1769731200000
  }
]

contact-list.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/contact-list.json",
  "title": "Contact list",
  "description": "A named list of contacts (lst_…), used as a broadcast audience. GET /api/lists/:id adds member_count; other responses return the bare row.",
  "type": "object",
  "required": [
    "id",
    "user_id",
    "name",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "List id (lst_…).",
      "examples": [
        "lst_5Wd9JqRs"
      ]
    },
    "user_id": {
      "type": "string",
      "description": "Owning account (usr_…).",
      "examples": [
        "usr_7Fj3MnQw"
      ]
    },
    "name": {
      "type": "string",
      "description": "Display name, unique per account.",
      "examples": [
        "Newsletter"
      ]
    },
    "member_count": {
      "type": "integer",
      "description": "How many contacts the list holds. Detail (GET one) responses only.",
      "examples": [
        1284
      ]
    },
    "created_at": {
      "type": "integer",
      "description": "When the list was created, in Unix epoch milliseconds (UTC).",
      "examples": [
        1769731200000
      ]
    },
    "updated_at": {
      "type": "integer",
      "description": "When the list last changed, in Unix epoch milliseconds (UTC).",
      "examples": [
        1769731200000
      ]
    }
  }
}

POST /api/lists Create a contact list. Returns the list with its id (lst_…); add contacts with addListContacts.

Create a contact list. Returns the list with its id (lst_…); add contacts with addListContacts.

Request body

create-list-request.json

Field	Type	Notes
name req	string

create-list-request.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/create-list-request.json",
  "title": "Create list request body",
  "type": "object",
  "required": [
    "name"
  ],
  "additionalProperties": false,
  "properties": {
    "name": {
      "type": "string"
    }
  }
}

Response body

contact-list.json

A named list of contacts (lst_…), used as a broadcast audience. GET /api/lists/:id adds member_count; other responses return the bare row.

Field	Type	Notes
id req	string	List id (lst_…).
user_id req	string	Owning account (usr_…).
name req	string	Display name, unique per account.
member_count	integer	How many contacts the list holds. Detail (GET one) responses only.
created_at req	integer	When the list was created, in Unix epoch milliseconds (UTC).
updated_at req	integer	When the list last changed, in Unix epoch milliseconds (UTC).

An actual response, recorded from the conformance suite.

response.json

{
  "id": "lst_5Wd9JqRs",
  "user_id": "usr_7Fj3MnQw",
  "name": "Newsletter",
  "created_at": 1769731200000,
  "updated_at": 1769731200000
}

contact-list.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/contact-list.json",
  "title": "Contact list",
  "description": "A named list of contacts (lst_…), used as a broadcast audience. GET /api/lists/:id adds member_count; other responses return the bare row.",
  "type": "object",
  "required": [
    "id",
    "user_id",
    "name",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "List id (lst_…).",
      "examples": [
        "lst_5Wd9JqRs"
      ]
    },
    "user_id": {
      "type": "string",
      "description": "Owning account (usr_…).",
      "examples": [
        "usr_7Fj3MnQw"
      ]
    },
    "name": {
      "type": "string",
      "description": "Display name, unique per account.",
      "examples": [
        "Newsletter"
      ]
    },
    "member_count": {
      "type": "integer",
      "description": "How many contacts the list holds. Detail (GET one) responses only.",
      "examples": [
        1284
      ]
    },
    "created_at": {
      "type": "integer",
      "description": "When the list was created, in Unix epoch milliseconds (UTC).",
      "examples": [
        1769731200000
      ]
    },
    "updated_at": {
      "type": "integer",
      "description": "When the list last changed, in Unix epoch milliseconds (UTC).",
      "examples": [
        1769731200000
      ]
    }
  }
}

GET /api/lists/:id Get one contact list with its member count.

Get one contact list with its member count.

Response body

contact-list.json

A named list of contacts (lst_…), used as a broadcast audience. GET /api/lists/:id adds member_count; other responses return the bare row.

Field	Type	Notes
id req	string	List id (lst_…).
user_id req	string	Owning account (usr_…).
name req	string	Display name, unique per account.
member_count	integer	How many contacts the list holds. Detail (GET one) responses only.
created_at req	integer	When the list was created, in Unix epoch milliseconds (UTC).
updated_at req	integer	When the list last changed, in Unix epoch milliseconds (UTC).

An actual response, recorded from the conformance suite.

response.json

{
  "id": "lst_5Wd9JqRs",
  "user_id": "usr_7Fj3MnQw",
  "name": "Newsletter",
  "created_at": 1769731200000,
  "updated_at": 1769731200000,
  "member_count": 1284
}

contact-list.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/contact-list.json",
  "title": "Contact list",
  "description": "A named list of contacts (lst_…), used as a broadcast audience. GET /api/lists/:id adds member_count; other responses return the bare row.",
  "type": "object",
  "required": [
    "id",
    "user_id",
    "name",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "List id (lst_…).",
      "examples": [
        "lst_5Wd9JqRs"
      ]
    },
    "user_id": {
      "type": "string",
      "description": "Owning account (usr_…).",
      "examples": [
        "usr_7Fj3MnQw"
      ]
    },
    "name": {
      "type": "string",
      "description": "Display name, unique per account.",
      "examples": [
        "Newsletter"
      ]
    },
    "member_count": {
      "type": "integer",
      "description": "How many contacts the list holds. Detail (GET one) responses only.",
      "examples": [
        1284
      ]
    },
    "created_at": {
      "type": "integer",
      "description": "When the list was created, in Unix epoch milliseconds (UTC).",
      "examples": [
        1769731200000
      ]
    },
    "updated_at": {
      "type": "integer",
      "description": "When the list last changed, in Unix epoch milliseconds (UTC).",
      "examples": [
        1769731200000
      ]
    }
  }
}

PATCH /api/lists/:id Rename a contact list.

Rename a contact list.

Request body

update-list-request.json

Field	Type	Notes
name req	string

update-list-request.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/update-list-request.json",
  "title": "Update list request body",
  "type": "object",
  "required": [
    "name"
  ],
  "additionalProperties": false,
  "properties": {
    "name": {
      "type": "string"
    }
  }
}

Response body

contact-list.json

A named list of contacts (lst_…), used as a broadcast audience. GET /api/lists/:id adds member_count; other responses return the bare row.

Field	Type	Notes
id req	string	List id (lst_…).
user_id req	string	Owning account (usr_…).
name req	string	Display name, unique per account.
member_count	integer	How many contacts the list holds. Detail (GET one) responses only.
created_at req	integer	When the list was created, in Unix epoch milliseconds (UTC).
updated_at req	integer	When the list last changed, in Unix epoch milliseconds (UTC).

An actual response, recorded from the conformance suite.

response.json

{
  "id": "lst_5Wd9JqRs",
  "user_id": "usr_7Fj3MnQw",
  "name": "Newsletter (EU)",
  "created_at": 1769731200000,
  "updated_at": 1769817600000
}

contact-list.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/contact-list.json",
  "title": "Contact list",
  "description": "A named list of contacts (lst_…), used as a broadcast audience. GET /api/lists/:id adds member_count; other responses return the bare row.",
  "type": "object",
  "required": [
    "id",
    "user_id",
    "name",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "List id (lst_…).",
      "examples": [
        "lst_5Wd9JqRs"
      ]
    },
    "user_id": {
      "type": "string",
      "description": "Owning account (usr_…).",
      "examples": [
        "usr_7Fj3MnQw"
      ]
    },
    "name": {
      "type": "string",
      "description": "Display name, unique per account.",
      "examples": [
        "Newsletter"
      ]
    },
    "member_count": {
      "type": "integer",
      "description": "How many contacts the list holds. Detail (GET one) responses only.",
      "examples": [
        1284
      ]
    },
    "created_at": {
      "type": "integer",
      "description": "When the list was created, in Unix epoch milliseconds (UTC).",
      "examples": [
        1769731200000
      ]
    },
    "updated_at": {
      "type": "integer",
      "description": "When the list last changed, in Unix epoch milliseconds (UTC).",
      "examples": [
        1769731200000
      ]
    }
  }
}

DELETE /api/lists/:id Delete a contact list. The list is removed; the contacts themselves are kept.

Delete a contact list. The list is removed; the contacts themselves are kept.

Response body

ok-response.json

The uniform acknowledgement for deletes and other actions with nothing else to report.

Field	Type	Notes
ok req	true	Always true — a non-2xx error body is returned otherwise.

ok-response.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/ok-response.json",
  "title": "OK",
  "description": "The uniform acknowledgement for deletes and other actions with nothing else to report.",
  "type": "object",
  "required": [
    "ok"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true,
      "description": "Always true — a non-2xx error body is returned otherwise."
    }
  }
}

GET /api/lists/:id/contacts List the contacts that are members of a list, newest first. Optionally page with `before` (a `last_seen_at`/`created_at` cursor) and `limit`. Response is a bare array — paginate by passing the last row's `last_seen_at` (or `created_at`) as the next `before`.

List the contacts that are members of a list, newest first. Optionally page with `before` (a `last_seen_at`/`created_at` cursor) and `limit`. Response is a bare array — paginate by passing the last row's `last_seen_at` (or `created_at`) as the next `before`.

Response body

array contact.json

One address-book contact. Contacts accrue automatically from inbound/outbound mail and imports; role addresses (info@, support@) and consent state are tracked so broadcast audiences stay clean.

Field	Type	Notes
id req	string	Contact id.
user_id req	string	Owning account (usr_…).
email req	string	The address, trimmed and lowercased.
name	string · null	Display name, when known.
first_name	string · null	First name, when known.
last_name	string · null	Last name, when known.
company	string · null	Company, when known.
website	string · null	Website URL, when known.
phone	string · null	Phone number, when known.
status req	"active" · "unsubscribed" · "archived"	Lifecycle state. Unsubscribed contacts are excluded from broadcast audiences.
source req	string	Where the contact came from: 'inbound', 'outbound', 'manual', 'import', or a connected provider ('google', 'microsoft', 'apple', …).
role	0 · 1	1 for a role/non-personal address (info@, support@, …).
subscribed	0 · 1	1 = marketing opt-in (tracked separately from suppression).
properties	string · null	Untyped custom fields as a JSON string, including { socials: {…} }.
external_id	string · null	Your identifier for this contact, when supplied.
first_seen_at	integer · null	First time mail was exchanged with this address, in Unix epoch milliseconds (UTC); null when it has never happened.
last_seen_at	integer · null	Most recent time mail was exchanged with this address, in Unix epoch milliseconds (UTC); null when it has never happened.
msg_count	integer	How many messages have been exchanged with this address.
created_at req	integer	When the contact was created, in Unix epoch milliseconds (UTC).
updated_at req	integer	When the contact last changed, in Unix epoch milliseconds (UTC).

An actual array of results, recorded from the conformance suite.

response.json

[
  {
    "id": "ctc_8Rt5NmZx",
    "user_id": "usr_7Fj3MnQw",
    "email": "ada@example.com",
    "name": "Ada Lovelace",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "company": null,
    "website": null,
    "phone": null,
    "status": "active",
    "source": "inbound",
    "role": 0,
    "subscribed": 1,
    "properties": null,
    "external_id": null,
    "first_seen_at": 1769731200000,
    "last_seen_at": 1769817600000,
    "msg_count": 4,
    "created_at": 1769731200000,
    "updated_at": 1769817600000
  }
]

contact.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/contact.json",
  "title": "Contact",
  "description": "One address-book contact. Contacts accrue automatically from inbound/outbound mail and imports; role addresses (info@, support@) and consent state are tracked so broadcast audiences stay clean.",
  "type": "object",
  "required": [
    "id",
    "user_id",
    "email",
    "status",
    "source",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "Contact id.",
      "examples": [
        "ctc_8Rt5NmZx"
      ]
    },
    "user_id": {
      "type": "string",
      "description": "Owning account (usr_…).",
      "examples": [
        "usr_7Fj3MnQw"
      ]
    },
    "email": {
      "type": "string",
      "description": "The address, trimmed and lowercased.",
      "examples": [
        "ada@example.com"
      ]
    },
    "name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Display name, when known.",
      "examples": [
        "Ada Lovelace"
      ]
    },
    "first_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "First name, when known."
    },
    "last_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Last name, when known."
    },
    "company": {
      "type": [
        "string",
        "null"
      ],
      "description": "Company, when known."
    },
    "website": {
      "type": [
        "string",
        "null"
      ],
      "description": "Website URL, when known."
    },
    "phone": {
      "type": [
        "string",
        "null"
      ],
      "description": "Phone number, when known."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "unsubscribed",
        "archived"
      ],
      "description": "Lifecycle state. Unsubscribed contacts are excluded from broadcast audiences."
    },
    "source": {
      "type": "string",
      "description": "Where the contact came from: 'inbound', 'outbound', 'manual', 'import', or a connected provider ('google', 'microsoft', 'apple', …).",
      "examples": [
        "inbound"
      ]
    },
    "role": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "1 for a role/non-personal address (info@, support@, …)."
    },
    "subscribed": {
      "type": "integer",
      "enum": [
        0,
        1
      ],
      "description": "1 = marketing opt-in (tracked separately from suppression)."
    },
    "properties": {
      "type": [
        "string",
        "null"
      ],
      "description": "Untyped custom fields as a JSON string, including { socials: {…} }."
    },
    "external_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Your identifier for this contact, when supplied."
    },
    "first_seen_at": {
      "type": [
        "integer",
        "null"
      ],
      "description": "First time mail was exchanged with this address, in Unix epoch milliseconds (UTC); null when it has never happened.",
      "examples": [
        1769731200000
      ]
    },
    "last_seen_at": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Most recent time mail was exchanged with this address, in Unix epoch milliseconds (UTC); null when it has never happened.",
      "examples": [
        1769731200000
      ]
    },
    "msg_count": {
      "type": "integer",
      "description": "How many messages have been exchanged with this address.",
      "examples": [
        4
      ]
    },
    "created_at": {
      "type": "integer",
      "description": "When the contact was created, in Unix epoch milliseconds (UTC).",
      "examples": [
        1769731200000
      ]
    },
    "updated_at": {
      "type": "integer",
      "description": "When the contact last changed, in Unix epoch milliseconds (UTC).",
      "examples": [
        1769731200000
      ]
    }
  }
}

POST /api/lists/:id/contacts Add contacts (by id, ctr_…) to a list. Returns how many were newly added; contacts already on the list are ignored.

Add contacts (by id, ctr_…) to a list. Returns how many were newly added; contacts already on the list are ignored.

Request body

add-list-contacts-request.json

Field	Type	Notes
contactIds req	string[]

add-list-contacts-request.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/add-list-contacts-request.json",
  "title": "Add contacts to list request body",
  "type": "object",
  "required": [
    "contactIds"
  ],
  "additionalProperties": false,
  "properties": {
    "contactIds": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

Response body

add-list-contacts-response.json

POST /api/lists/:id/contacts — how many contacts were actually added (already-present members don't count twice).

Field	Type	Notes
added req	integer	Contacts newly added to the list.

add-list-contacts-response.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/add-list-contacts-response.json",
  "title": "Add list contacts response",
  "description": "POST /api/lists/:id/contacts — how many contacts were actually added (already-present members don't count twice).",
  "type": "object",
  "required": [
    "added"
  ],
  "properties": {
    "added": {
      "type": "integer",
      "description": "Contacts newly added to the list.",
      "examples": [
        3
      ]
    }
  }
}

DELETE /api/lists/:id/contacts/:contactId Remove one contact from a list (the contact itself is kept).

Remove one contact from a list (the contact itself is kept).

Response body

ok-response.json

The uniform acknowledgement for deletes and other actions with nothing else to report.

Field	Type	Notes
ok req	true	Always true — a non-2xx error body is returned otherwise.

ok-response.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://api.mailkite.dev/v1/schemas/ok-response.json",
  "title": "OK",
  "description": "The uniform acknowledgement for deletes and other actions with nothing else to report.",
  "type": "object",
  "required": [
    "ok"
  ],
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true,
      "description": "Always true — a non-2xx error body is returned otherwise."
    }
  }
}