Custom Fields

Define custom contact fields

Manage contact fields

Get all Contact Fields

get

Get all Contact Fields existing in your account

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

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

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/fields

Node.jsPHPPythonRubyC#Java

const { MailtrapClient } = require("mailtrap");
const client = new MailtrapClient({ token: "YOUR_API_KEY", accountId: YOUR_ACCOUNT_ID });
const fields = await client.contacts.fields.getAll();
fields.forEach(field => console.log(`${field.name}: ${field.data_type}`));

[
  {
    "id": 6730,
    "name": "First name",
    "type": "text",
    "merge_tag": "first_name"
  },
  {
    "id": 6731,
    "name": "Birthdate",
    "type": "date",
    "merge_tag": "birthdate"
  },
  {
    "id": 6732,
    "name": "Cats count",
    "type": "integer",
    "merge_tag": "cats_count"
  }
]

Create Contact Field

post

Create new Contact Fields. Please note, you can have up to 40 fields.

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

namestring · max: 80Optional

data_typestring · enumOptionalPossible values:

merge_tagstring · max: 80Optional

Personalize your campaigns by adding a merge tag. This field will be replaced with unique contact details for each recipient.

Responses

201

Contact Field Created.

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

Node.jsPHPPythonRubyC#Java

const { MailtrapClient } = require("mailtrap");
const client = new MailtrapClient({ token: "YOUR_API_KEY", accountId: YOUR_ACCOUNT_ID });
const field = await client.contacts.fields.create({ name: "Company", data_type: "text", merge_tag: "company" });
console.log(`Field created: ${field.id}`);

{
  "id": 26730,
  "name": "My Contact Field",
  "data_type": "text",
  "merge_tag": "my_contact_field"
}

Get Contact Field

get

Get a contact Field by ID

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

field_idinteger · int64 · min: 1Required

Unique Contact Field ID

Example: 3229

Responses

200

Returns attributes of the contact field.

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/fields/{field_id}

Node.jsPHPPythonRubyC#Java

const { MailtrapClient } = require("mailtrap");
const client = new MailtrapClient({ token: "YOUR_API_KEY", accountId: YOUR_ACCOUNT_ID });
const field = await client.contacts.fields.get(fieldId);
console.log(`Field: ${field.name} (${field.data_type})`);

{
  "id": 26730,
  "name": "My Contact Field",
  "data_type": "text",
  "merge_tag": "my_contact_field"
}

Delete Contact Field

delete

Delete existing Contact Field Please, note, you cannot delete a Contact Field which is used in Automations, Email Campaigns (started or scheduled), and in conditions of Contact Segments (you'll see the corresponding error)

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

field_idinteger · int64 · min: 1Required

Unique Contact Field ID

Example: 3229

Responses

204

Contact Field 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

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

delete

/api/accounts/{account_id}/contacts/fields/{field_id}

Node.jsPHPPythonRubyC#Java

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

No content

Update Contact Field

patch

Update existing Contact Field. Please note, you cannot change data_type of the field.

Authorizations

HeaderAuthBearerAuth

Api-TokenstringRequired

Pass the API token in the Api-Token

Path parameters

account_idinteger · int64 · min: 1Required

Unique account ID

Example: 3229

field_idinteger · int64 · min: 1Required

Unique Contact Field ID

Example: 3229

Body

application/json

namestring · max: 80Optional

merge_tagstring · max: 80Optional

Personalize your campaigns by adding a merge tag. This field will be replaced with unique contact details for each recipient.

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

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/fields/{field_id}

Node.jsPHPPythonRubyC#Java

const { MailtrapClient } = require("mailtrap");
const client = new MailtrapClient({ token: "YOUR_API_KEY", accountId: YOUR_ACCOUNT_ID });
const field = await client.contacts.fields.update(fieldId, { name: "Updated Name", merge_tag: "updated_name" });

{
  "id": 6730,
  "name": "Updated name",
  "data_type": "text",
  "merge_tag": "updated_name"
}