Contact Lists

Organize contacts into lists

Manage contact lists

Get all Contact Lists

get

Get all contact lists existing in your account

Authorizations

Api-TokenstringRequired

Pass the API token in the Api-Token

Query parameters

searchstringOptional

Filter contact lists by name (case-insensitive prefix match).

Example: news

Responses

200

OK.

application/json

idintegerOptional

namestring · max: 255Optional

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

429

Rate limit exceeded for the current account.

application/json

500

Internal error. Retry later or contact support.

application/json

get/api/contacts/lists

curl -X GET https://mailtrap.io/api/contacts/lists \
  -H 'Authorization: Bearer YOUR_API_KEY'

# Filter lists by name (case-insensitive prefix match)
curl -X GET 'https://mailtrap.io/api/contacts/lists?search=news' \
  -H 'Authorization: Bearer YOUR_API_KEY'

[
  {
    "id": 26730,
    "name": "Customers"
  },
  {
    "id": 26731,
    "name": "Old Contacts"
  }
]

Create Contact List

post

Create new Contact Lists

Authorizations

Api-TokenstringRequired

Pass the API token in the Api-Token

Body

namestringOptional

Responses

200

Contact List Created.

application/json

idintegerOptional

namestring · max: 255Optional

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

429

Rate limit exceeded for the current account.

application/json

500

Internal error. Retry later or contact support.

application/json

post/api/contacts/lists

curl -X POST https://mailtrap.io/api/contacts/lists \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Customers"}'

{
  "id": 26730,
  "name": "Customers"
}

Get Contact List

get

Get a contact list by ID

Authorizations

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

list_idinteger · int64 · min: 1Required

Unique list ID

Example: 3229

Responses

200

Returns attributes of the contact list.

application/json

idintegerOptional

namestring · max: 255Optional

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Resource not found

application/json

429

Rate limit exceeded for the current account.

application/json

500

Internal error. Retry later or contact support.

application/json

get/api/contacts/lists/{list_id}

curl -X GET https://mailtrap.io/api/contacts/lists/{list_id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": 26730,
  "name": "My Contact List"
}

Delete Contact List

delete

Delete existing Contact List

Authorizations

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

list_idinteger · int64 · min: 1Required

Unique list ID

Example: 3229

Responses

204

Contact List successfully deleted

No content

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Resource not found

application/json

429

Rate limit exceeded for the current account.

application/json

500

Internal error. Retry later or contact support.

application/json

delete/api/contacts/lists/{list_id}

curl -X DELETE https://mailtrap.io/api/contacts/lists/{list_id} \
  -H 'Authorization: Bearer YOUR_API_KEY'

No content

Update Contact List

patch

Update existing Contact List

Authorizations

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

list_idinteger · int64 · min: 1Required

Unique list ID

Example: 3229

Body

namestring · max: 255Optional

Responses

200

OK.

application/json

idintegerOptional

namestring · max: 255Optional

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

Resource not found

application/json

429

Rate limit exceeded for the current account.

application/json

500

Internal error. Retry later or contact support.

application/json

patch/api/contacts/lists/{list_id}

curl -X PATCH https://mailtrap.io/api/contacts/lists/{list_id} \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Former Customers"}'

{
  "id": 26730,
  "name": "Former Customers"
}