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

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

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

409

A Contact with the same email is already being created.

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/accounts/{account_id}/contacts

Node.jsPHPPythonRuby.NETJava

import { MailtrapClient } from "mailtrap";

const client = new MailtrapClient({
  token: "YOUR_API_TOKEN"
});

const contact = await client.contacts.create({
  email: "[email protected]",
  fields: {
    first_name: "John",
    last_name: "Smith",
    company: "Example Inc"
  },
  list_ids: [1, 2, 3]
});

console.log(`Contact created: ${contact.email}`);

{
  "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

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

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

Node.jsPHPPythonRuby.NETJava

import { MailtrapClient } from "mailtrap";

const client = new MailtrapClient({
  token: "YOUR_API_TOKEN"
});

// Get by contact ID
const contact = await client.contacts.get(contactId);

// Or get by email (URL encoded)
const contactByEmail = await client.contacts.get(
  encodeURIComponent("[email protected]")
);

console.log(`Contact: ${contact.email}`);
console.log(`Status: ${contact.status}`);

{
  "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

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

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

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

Node.jsPHPPythonRubyC#Java

const { MailtrapClient } = require("mailtrap");
const client = new MailtrapClient({ token: "YOUR_API_KEY", accountId: "YOUR_ACCOUNT_ID" });
await client.contacts.delete("contact_id_or_email");

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

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

contact_identifierstring · uuid or emailRequired

Contact UUID or Email

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

Body

application/json

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

409

A Contact with the same email is already being created.

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

Node.jsPHPPythonRubyC#Java

const { MailtrapClient } = require("mailtrap");
const client = new MailtrapClient({ token: "YOUR_API_KEY", accountId: "YOUR_ACCOUNT_ID" });
const updatedContact = await client.contacts.update("contact_id_or_email", { 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
  }
}