Contacts
Manage individual contacts
Manage contacts
Returns a paginated list of the account's contacts.
Pagination is cursor based. Every response carries a pagination object; pass its next_token value back as the token query parameter to fetch the next page, and stop when next_token is null. Cursors cannot be walked backwards, so prev_token and prev_url are always null. No total count is returned.
Pass the API token in the Api-Token
Return only contacts that belong to this contact list.
3229Return only contacts with this subscription status. Matches the status field of the
returned contact.
subscribedPossible values: Return only contacts whose email contains this value (case-insensitive substring match).
* and ? are matched literally, not as wildcards.
john@Number of contacts per page. Defaults to 25, maximum 50. Larger values are clamped
to the maximum.
25Example: 25Opaque cursor taken from the next_token of a previous response. Omit it to fetch the
first page. Tokens are not page numbers and must not be constructed by hand.
WzE3NDI4MjA2MDAyMzAsIjAxOGRkNWUzLWY2ZDItN2MwMC04ZjliLWU1YzNmMmQ4YTEzMiJdA paginated list of contacts.
Returns unauthorized error message. Check your credentials.
Returns forbidden error message. Check your permissions.
A filter value or the pagination cursor was invalid. The request is rejected instead of the filter being ignored.
Rate limit exceeded for the current account.
Internal error. Retry later or contact support.
curl -X GET https://mailtrap.io/api/contacts \
-H 'Authorization: Bearer YOUR_API_KEY'
# Filter by list, status and email substring
curl -X GET 'https://mailtrap.io/api/contacts?list_id=3229&status=subscribed&email=john%40' \
-H 'Authorization: Bearer YOUR_API_KEY'
# Fetch the next page using the cursor from the previous response
curl -X GET 'https://mailtrap.io/api/contacts?per_page=25&token=WzE3NDI4MjA2MDAyMzAsIjAxOGRkNWUzLWY2ZDItN2MwMC04ZjliLWU1YzNmMmQ4YTEzMiJd' \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"data": [
{
"id": "018dd5e3-f6d2-7c00-8f9b-e5c3f2d8a132",
"email": "john.smith@example.com",
"created_at": 1742820600230,
"updated_at": 1742820600230,
"list_ids": [
1,
2
],
"status": "subscribed",
"fields": {
"first_name": "John",
"last_name": "Smith"
}
},
{
"id": "018dd5e3-f6d2-7c00-8f9b-000000000002",
"email": "jane.doe@example.com",
"created_at": 1742906999123,
"updated_at": 1742906999123,
"list_ids": [
3
],
"status": "unsubscribed",
"fields": {}
}
],
"pagination": {
"token": null,
"prev_token": null,
"next_token": "WzE3NDI5MDY5OTkxMjMsIjAxOGRkNWUzLWY2ZDItN2MwMC04ZjliLTAwMDAwMDAwMDAwMiJd",
"first_url": "https://mailtrap.io/api/contacts?per_page=25",
"prev_url": null,
"current_url": "https://mailtrap.io/api/contacts?per_page=25",
"next_url": "https://mailtrap.io/api/contacts?per_page=25&token=WzE3NDI5MDY5OTkxMjMsIjAxOGRkNWUzLWY2ZDItN2MwMC04ZjliLTAwMDAwMDAwMDAwMiJd"
}
}Create a new contact
Pass the API token in the Api-Token
Contact created successfully.
Returns unauthorized error message. Check your credentials.
Returns forbidden error message. Check your permissions.
Returns validation errors.
Rate limit exceeded for the current account.
Internal error. Retry later or contact support.
curl -X POST https://mailtrap.io/api/contacts \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"contact": {
"email": "john.smith@example.com",
"fields": {"first_name": "John", "last_name": "Smith", "company": "Example Inc"},
"list_ids": [1, 2, 3]
}
}'
{
"data": {
"id": "018dd5e3-f6d2-7c00-8f9b-e5c3f2d8a132",
"status": "subscribed",
"email": "john.smith@example.com",
"fields": {
"first_name": "John",
"last_name": "Smith"
},
"list_ids": [
1,
2,
3
],
"created_at": 1742820600230,
"updated_at": 1742820600230
}
}Get contact using UUID or email (URL encoded)
Pass the API token in the Api-Token
Contact UUID or Email
018dd5e3-f6d2-7c00-8f9b-e5c3f2d8a132OK.
Returns unauthorized error message. Check your credentials.
Returns forbidden error message. Check your permissions.
Resource not found
Rate limit exceeded for the current account.
Internal error. Retry later or contact support.
curl -X GET https://mailtrap.io/api/contacts/{contact_identifier} \
-H 'Authorization: Bearer YOUR_API_KEY'
{
"data": {
"id": "018dd5e3-f6d2-7c00-8f9b-e5c3f2d8a132",
"status": "subscribed",
"email": "john.smith@example.com",
"fields": {
"first_name": "John",
"last_name": "Smith"
},
"list_ids": [
1,
2,
3
],
"created_at": 1742820600230,
"updated_at": 1742820600230
}
}Delete contact using UUID or email (URL encoded)
Pass the API token in the Api-Token
Contact UUID or Email
018dd5e3-f6d2-7c00-8f9b-e5c3f2d8a132Contact successfully deleted
No content
Returns unauthorized error message. Check your credentials.
Returns forbidden error message. Check your permissions.
No contact for the given identifier. The JSON body uses an errors string (not the error key used by some other 404 responses).
Rate limit exceeded for the current account.
Internal error. Retry later or contact support.
curl -X DELETE https://mailtrap.io/api/contacts/{contact_identifier} \
-H 'Authorization: Bearer YOUR_API_KEY'
No content
Update contact using UUID or email (URL encoded)
Pass the API token in the Api-Token
Contact UUID or Email
018dd5e3-f6d2-7c00-8f9b-e5c3f2d8a132OK.
Performed action on the contact:
- "created" if contact does not exist
- "updated" if contact exists
Returns unauthorized error message. Check your credentials.
Returns forbidden error message. Check your permissions.
Returns validation errors.
Rate limit exceeded for the current account.
Internal error. Retry later or contact support.
curl -X PATCH https://mailtrap.io/api/contacts/{contact_identifier} \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"contact": { "email": "new@example.com", "fields": {"first_name": "John"}}}'
{
"action": "updated",
"data": {
"id": "018dd5e3-f6d2-7c00-8f9b-e5c3f2d8a132",
"status": "subscribed",
"email": "john.smith@example.com",
"fields": {
"first_name": "John",
"last_name": "Smith"
},
"list_ids": [
1,
2,
3
],
"created_at": 1740659901189,
"updated_at": 1742903266889
}
}Last updated
Was this helpful?