Contact Lists

Contact lists are static groups you manually curate. Use them to target specific audiences in email campaigns.

Authentication

All endpoints require:

Authorization: Bearer YOUR_API_KEY
X-Project-ID: YOUR_PROJECT_ID (or encoded in the API key)

Endpoints

Method	Path	Description
`GET`	`/api/v1/contacts/lists`	List all contact lists
`POST`	`/api/v1/contacts/lists`	Create a list
`GET`	`/api/v1/contacts/lists/:id`	Get a single list
`PATCH`	`/api/v1/contacts/lists/:id`	Update a list
`DELETE`	`/api/v1/contacts/lists/:id`	Delete a list
`GET`	`/api/v1/contacts/lists/:id/members`	Get list members
`POST`	`/api/v1/contacts/lists/:id/members`	Add a contact to a list
`DELETE`	`/api/v1/contacts/lists/:id/members`	Remove a contact from a list

List All Contact Lists

GET https://api.usegately.com/api/v1/contacts/lists

SDK

const lists = await crm.listContactLists()

Response

[
  {
    "id": "list-uuid",
    "project_id": "proj-uuid",
    "name": "Newsletter Subscribers",
    "description": "Monthly newsletter opt-ins",
    "created_at": "2025-01-01T00:00:00.000Z"
  }
]

Create a List

POST https://api.usegately.com/api/v1/contacts/lists

Body

{ "name": "Newsletter Subscribers", "description": "Monthly newsletter opt-ins" }

SDK

const list = await crm.createContactList({
  name: 'Newsletter Subscribers',
  description: 'Monthly newsletter opt-ins',
})

Update a List

PATCH https://api.usegately.com/api/v1/contacts/lists/LIST_ID

SDK

await crm.updateContactList('LIST_ID', { name: 'Weekly Newsletter' })

Delete a List

Deletes the list. Contacts are not deleted.

DELETE https://api.usegately.com/api/v1/contacts/lists/LIST_ID

SDK

await crm.deleteContactList('LIST_ID')

Get List Members

GET https://api.usegately.com/api/v1/contacts/lists/LIST_ID/members?page=1&limit=100

SDK

const members = await crm.getListMembers('LIST_ID', { page: 1, limit: 100 })

Response

[
  {
    "contact_id": "contact-uuid",
    "list_id": "list-uuid",
    "added_at": "2025-03-01T10:00:00.000Z",
    "crm_contacts": { "id": "contact-uuid", "name": "Jane Smith", "email": "jane@example.com" }
  }
]

Add Contact to List

POST https://api.usegately.com/api/v1/contacts/lists/LIST_ID/members

Body

{ "contact_id": "CONTACT_ID" }

SDK

await crm.addContactToList('LIST_ID', 'CONTACT_ID')

Remove Contact from List

DELETE https://api.usegately.com/api/v1/contacts/lists/LIST_ID/members?contact_id=CONTACT_ID

SDK

await crm.removeContactFromList('LIST_ID', 'CONTACT_ID')

TypeScript Type

interface ContactList {
  id: string
  project_id: string
  name: string
  description?: string | null
  created_at: string
  updated_at?: string
}

Overview

Authentication

Members

Project Settings

Email Campaigns

Plans

Contacts

Discussions

Transactional Email

Webhooks

Authentication

Endpoints

List All Contact Lists

Create a List

Update a List

Delete a List

Get List Members

Add Contact to List

Remove Contact from List

TypeScript Type

​Authentication

​Endpoints

​List All Contact Lists

​Create a List

​Update a List

​Delete a List

​Get List Members

​Add Contact to List

​Remove Contact from List

​TypeScript Type

Authentication

Endpoints

List All Contact Lists

Create a List

Update a List

Delete a List

Get List Members

Add Contact to List

Remove Contact from List

TypeScript Type