Contacts

Create, list, update, and delete contacts. Retrieve a contact's sends, scheduled sends, sequence enrolments, segment memberships, and timeline.

Contacts represent the people in your audience. Each contact has a unique email address and a set of custom properties you can use for personalisation and segmentation.

Create contact

POST /api/contacts

Creates a new contact. The email address must be unique within your organisation.

Request body

Field	Type	Required	Description
`email`	string	Yes	The contact's email address.
`properties`	object	No	Key-value pairs of custom properties (e.g. `firstName`, `plan`).

Response

Returns the created contact with a generated id.

{
  "id": "cnt_01H8MZXK...",
  "email": "alice@example.com",
  "properties": { "firstName": "Alice", "plan": "pro" },
  "suppressed": false,
  "createdAt": "2025-09-15T10:30:00.000Z",
  "updatedAt": "2025-09-15T10:30:00.000Z"
}

Errors

Code	Description
`VALIDATION_ERROR`	Missing or invalid email address.
`CONFLICT`	A contact with this email already exists.

Examples

curl -X POST https://api.kraiter.com/api/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "properties": { "firstName": "Alice", "plan": "pro" }
  }'

const contact = await kraiter.contacts.create({
  email: "alice@example.com",
  properties: { firstName: "Alice", plan: "pro" },
});

List contacts

GET /api/contacts

Returns a paginated list of contacts. Supports filtering by suppression status and searching by email.

Query parameters

Parameter	Type	Default	Description
`cursor`	string	—	Pagination cursor from a previous response.
`limit`	number	20	Number of contacts to return (max 100).
`search`	string	—	Search contacts by email (partial match).
`suppressed`	boolean	—	Filter by suppression status.

Response

{
  "data": [
    {
      "id": "cnt_01H8MZXK...",
      "email": "alice@example.com",
      "properties": { "firstName": "Alice" },
      "suppressed": false,
      "createdAt": "2025-09-15T10:30:00.000Z",
      "updatedAt": "2025-09-15T10:30:00.000Z"
    }
  ],
  "nextCursor": "eyJpZCI6ImNudF8wMUgi..."
}

Examples

curl "https://api.kraiter.com/api/contacts?limit=10&search=alice" \
  -H "Authorization: Bearer YOUR_API_KEY"

const page = await kraiter.contacts.list({
  limit: 10,
  search: "alice",
});

Get contact

GET /api/contacts/:id

Returns a single contact by ID.

Path parameters

Parameter	Type	Description
`id`	string	The contact ID.

Response

Returns the full contact object.

Errors

Code	Description
`NOT_FOUND`	No contact with this ID exists.

Examples

curl https://api.kraiter.com/api/contacts/cnt_01H8MZXK... \
  -H "Authorization: Bearer YOUR_API_KEY"

const contact = await kraiter.contacts.get("cnt_01H8MZXK...");

Update contact

PATCH /api/contacts/:id

Updates a contact's email or properties. Only the fields you include are changed — omitted fields remain unchanged.

Path parameters

Parameter	Type	Description
`id`	string	The contact ID.

Request body

Field	Type	Required	Description
`email`	string	No	New email address.
`properties`	object	No	Properties to merge with existing properties.

Response

Returns the updated contact.

Errors

Code	Description
`NOT_FOUND`	No contact with this ID exists.
`CONFLICT`	The new email address is already in use.

Examples

curl -X PATCH https://api.kraiter.com/api/contacts/cnt_01H8MZXK... \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "properties": { "plan": "enterprise" } }'

const contact = await kraiter.contacts.update("cnt_01H8MZXK...", {
  properties: { plan: "enterprise" },
});

Delete contact

DELETE /api/contacts/:id

Permanently deletes a contact. This also removes any sequence enrolments and scheduled sends for the contact.

Path parameters

Parameter	Type	Description
`id`	string	The contact ID.

Response

Returns 204 No Content on success.

Errors

Code	Description
`NOT_FOUND`	No contact with this ID exists.

Examples

curl -X DELETE https://api.kraiter.com/api/contacts/cnt_01H8MZXK... \
  -H "Authorization: Bearer YOUR_API_KEY"

await kraiter.contacts.delete("cnt_01H8MZXK...");

List sends for contact

GET /api/contacts/:id/sends

Returns all emails sent to a specific contact.

Path parameters

Parameter	Type	Description
`id`	string	The contact ID.

Response

{
  "data": [
    {
      "id": "snd_01H9...",
      "templateId": "welcome-email",
      "status": "delivered",
      "sentAt": "2025-09-15T11:00:00.000Z"
    }
  ],
  "nextCursor": null
}

Examples

curl "https://api.kraiter.com/api/contacts/cnt_01H8MZXK.../sends" \
  -H "Authorization: Bearer YOUR_API_KEY"

const sends = await kraiter.contacts.listSends("cnt_01H8MZXK...");

List scheduled sends for contact

GET /api/contacts/:id/scheduled

Returns pending scheduled sends for a contact.

Path parameters

Parameter	Type	Description
`id`	string	The contact ID.

Response

Returns a paginated list of scheduled send objects.

Examples

curl "https://api.kraiter.com/api/contacts/cnt_01H8MZXK.../scheduled" \
  -H "Authorization: Bearer YOUR_API_KEY"

const scheduled = await kraiter.contacts.listScheduled("cnt_01H8MZXK...");

List sequence enrolments for contact

GET /api/contacts/:id/sequences

Returns the sequences a contact is currently enrolled in or has previously completed.

Path parameters

Parameter	Type	Description
`id`	string	The contact ID.

Response

{
  "data": [
    {
      "sequenceId": "onboarding",
      "status": "active",
      "enrolledAt": "2025-09-15T10:30:00.000Z",
      "currentStep": 2
    }
  ],
  "nextCursor": null
}

Examples

curl "https://api.kraiter.com/api/contacts/cnt_01H8MZXK.../sequences" \
  -H "Authorization: Bearer YOUR_API_KEY"

const enrolments = await kraiter.contacts.listSequences("cnt_01H8MZXK...");

List segment memberships for contact

GET /api/contacts/:id/segments

Returns the segments a contact currently belongs to.

Path parameters

Parameter	Type	Description
`id`	string	The contact ID.

Response

{
  "data": [
    {
      "segmentId": "seg_01H9...",
      "name": "Active Users",
      "joinedAt": "2025-09-15T10:30:00.000Z"
    }
  ],
  "nextCursor": null
}

Examples

curl "https://api.kraiter.com/api/contacts/cnt_01H8MZXK.../segments" \
  -H "Authorization: Bearer YOUR_API_KEY"

const segments = await kraiter.contacts.listSegments("cnt_01H8MZXK...");

Get contact timeline

GET /api/contacts/:id/timeline

Returns a unified timeline of events and sends for a contact, sorted in reverse chronological order.

Path parameters

Parameter	Type	Description
`id`	string	The contact ID.

Response

{
  "data": [
    {
      "type": "send",
      "id": "snd_01H9...",
      "templateId": "welcome-email",
      "status": "delivered",
      "timestamp": "2025-09-15T11:00:00.000Z"
    },
    {
      "type": "event",
      "name": "page_viewed",
      "properties": { "url": "/pricing" },
      "timestamp": "2025-09-15T10:45:00.000Z"
    }
  ],
  "nextCursor": null
}

Examples

curl "https://api.kraiter.com/api/contacts/cnt_01H8MZXK.../timeline" \
  -H "Authorization: Bearer YOUR_API_KEY"

const timeline = await kraiter.contacts.getTimeline("cnt_01H8MZXK...");

Contacts

On this page