Contacts

Manage individual contacts

Manage contacts

Create a new Contact

post

Create a new contact

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Body

application/json

Responses

201

Contact created successfully.

application/json

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

422

Returns validation errors.

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

cURLNode.jsPHPPythonRuby.NETJava

curl -X POST https://mailtrap.io/api/contacts \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "contact": {
      "email": "[email protected]",
      "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": "[email protected]",
    "fields": {
      "first_name": "John",
      "last_name": "Smith"
    },
    "list_ids": [
      1,
      2,
      3
    ],
    "created_at": 1742820600230,
    "updated_at": 1742820600230
  }
}

Get contact

get

Get contact using UUID or email (URL encoded)

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

contact_identifierstring · uuid or emailRequired

Contact UUID or Email

Example: 018dd5e3-f6d2-7c00-8f9b-e5c3f2d8a132

Responses

200

OK.

application/json

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/{contact_identifier}

cURLNode.jsPHPPythonRuby.NETJava

curl -X GET https://mailtrap.io/api/contacts/{contact_identifier} \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

{
  "data": {
    "id": "018dd5e3-f6d2-7c00-8f9b-e5c3f2d8a132",
    "status": "subscribed",
    "email": "[email protected]",
    "fields": {
      "first_name": "John",
      "last_name": "Smith"
    },
    "list_ids": [
      1,
      2,
      3
    ],
    "created_at": 1742820600230,
    "updated_at": 1742820600230
  }
}

Delete contact

delete

Delete contact using UUID or email (URL encoded)

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

contact_identifierstring · uuid or emailRequired

Contact UUID or Email

Example: 018dd5e3-f6d2-7c00-8f9b-e5c3f2d8a132

Responses

204

Contact successfully deleted

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

404

No contact for the given identifier. The JSON body uses an errors string (not the error key used by some other 404 responses).

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/{contact_identifier}

cURLNode.jsPHPPythonRubyC#Java

curl -X DELETE https://mailtrap.io/api/contacts/{contact_identifier} \
  -H 'Authorization: Bearer YOUR_API_TOKEN'

No content

Update contact

patch

Update contact using UUID or email (URL encoded)

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

contact_identifierstring · uuid or emailRequired

Contact UUID or Email

Example: 018dd5e3-f6d2-7c00-8f9b-e5c3f2d8a132

Body

application/json

Responses

200

OK.

application/json

actionstring · enumOptional

Performed action on the contact:

• "created" if contact does not exist
• "updated" if contact exists

Possible values:

401

Returns unauthorized error message. Check your credentials.

application/json

403

Returns forbidden error message. Check your permissions.

application/json

422

Returns validation errors.

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/{contact_identifier}

cURLNode.jsPHPPythonRubyC#Java

curl -X PATCH https://mailtrap.io/api/contacts/{contact_identifier} \
  -H 'Authorization: Bearer YOUR_API_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"contact": { "email": "[email protected]", "fields": {"first_name": "John"}}}'

{
  "action": "updated",
  "data": {
    "id": "018dd5e3-f6d2-7c00-8f9b-e5c3f2d8a132",
    "status": "subscribed",
    "email": "[email protected]",
    "fields": {
      "first_name": "John",
      "last_name": "Smith"
    },
    "list_ids": [
      1,
      2,
      3
    ],
    "created_at": 1740659901189,
    "updated_at": 1742903266889
  }
}