Skip to content
Skip to main content

Lists

The Lists endpoints let you manage typed collections of values (email addresses, domains, or top-level domains) that can be referenced by Rules using the in_list condition operator. Lists provide a way to maintain dynamic allow lists and block lists that are evaluated during inbound rule processing and outbound send evaluation without needing to update individual rules.

Each list has a type that determines what kind of values it accepts and which rule condition fields it can be matched against:

  • domain — Domain names (for example, example.com). Matched against the from.domain or recipient.domain rule condition.
  • tld — Top-level domains (for example, com, xyz). Matched against the from.tld or recipient.tld rule condition.
  • address — Full email addresses (for example, [email protected]). Matched against the from.address or recipient.address rule condition.

List type is set at creation time and cannot be changed. Items within a list are managed via the /v3/lists/{list_id}/items sub-resource endpoints. Values are automatically normalized (lowercased and trimmed) and validated against the list's type. Duplicate additions are silently ignored. You can submit up to 1000 items per add or remove request, and each item value can be at most 500 characters.

Endpoints

8
GET
List lists
GET /v3/lists

Returns all lists for your application.

POST
Create a list
POST /v3/lists

Creates a list for your application. Lists are typed collections of values (domains, TLDs, or email addresses) that can be referenced by rules using the in list condition operator. The list's type is...

GET
Get a list
GET /v3/lists/{list_id}

Returns the specified list.

PUT
Update a list
PUT /v3/lists/{list_id}

Updates the specified list. Only name and description can be updated. The list type is immutable after creation.

DELETE
Delete a list
DELETE /v3/lists/{list_id}

Deletes the specified list. This action is irreversible and cascades to all items in the list. Rules that reference the list through an in list condition no longer match its values after deletion.

GET
List items in a list
GET /v3/lists/{list_id}/items

Returns the items in the specified list.

POST
Add items to a list
POST /v3/lists/{list_id}/items

Adds items to the specified list. Values are normalized (lowercased and trimmed) and validated against the list's type — domain lists accept domain names, tld lists accept top-level domains, and addre...

DELETE
Remove items from a list
DELETE /v3/lists/{list_id}/items

Removes the specified items from the list. Values not currently in the list are silently ignored. The response returns the updated List object with a refreshed items count. You can submit up to 1000 i...