Create Contact

Create a new contact in your easymail account.

Request

POST /contacts

Request Body

Parameter	Type	Required	Description
email	string	Yes	Contact's email address (must be valid email format)
first_name	string	No	Contact's first name (max 255 characters)
last_name	string	No	Contact's last name (max 255 characters)
phone	string	No	Contact's phone number (max 32 characters)
external_id	string	No	External identifier for integration purposes (max 255 characters). Must be unique within your account
language	string	No	ISO 639-1 language code (2 characters, e.g., "en", "pl")
country_code	string	No	ISO 3166-1 alpha-2 country code (2 characters, e.g., "US", "PL")
timezone_uuid	string|null	No	UUID of the timezone to assign to the contact, from List Timezones. Send null to leave it unset. An unknown UUID returns 404. Read it back with Get Contact.
contact_lists	array of strings	No	UUIDs of contact lists the new contact should be subscribed to
custom_fields	array	No	Custom field values to set on the new contact (see Custom Fields section below)

When contact_lists is provided, every list UUID must belong to your account — otherwise the request is rejected and no contact is created.

Example Request

curl -X POST "https://email.easy.tools/api/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+48123456789",
    "external_id": "customer_123",
    "language": "en",
    "country_code": "US",
    "contact_lists": [
      "9f3c2a1e-8b7d-4e2f-a1c6-2d4f5e6a7b8c",
      "7a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d"
    ]
  }'

Custom Fields

Set custom field values on the new contact by including the custom_fields array. Each field_key must reference a custom field that already exists in your account; unknown keys are rejected with 422 and no contact is created.

Custom Field Object

Field	Type	Required	Description
field_key	string	Yes	The unique key of the custom field
value	mixed	Yes (key must be present)	The value to set (type depends on the field type). The value key must be present on each entry, but it may be null or "", which sets no value for that field.

Supported Field Types and Value Formats

Field Type	Expected Value	Example
text	string or numeric (max 255 characters)	"Acme Inc", 123
number	numeric	42, 3.14, "100"
boolean	bool, or string/int representation	true, false, "yes", "no", 1, 0
date	date string	"2025-01-15", "15/01/2025", "01-15-2025"
datetime	datetime string	"2025-01-15T10:30:00", "2025-01-15 10:30:00", "2025-01-15T10:30"
select	string (must match a predefined option)	"enterprise"
list	array of strings (max 100 elements, each ≤255 chars)	["Webinar X", "Webinar Y"]

Supported Date Formats

A date value accepts any of these:

• Y-m-d (e.g. "2025-01-15"), and the same date with a time component: Y-m-d\TH:i:s, Y-m-d\TH:i:sP, Y-m-d H:i:s
• European: d/m/Y, d-m-Y, d.m.Y (each with an optional H:i:s time)
• US: m/d/Y, m-d-Y (each with an optional H:i:s time)

Only the date part is stored; any time component is discarded.

Supported DateTime Formats

A datetime value accepts only these, and must match one of them exactly (no timezone offset or trailing Z):

• Y-m-d\TH:i:s (e.g. "2025-01-15T10:30:00")
• Y-m-d H:i:s (e.g. "2025-01-15 10:30:00")
• Y-m-d\TH:i (e.g. "2025-01-15T10:30")
• Y-m-d H:i (e.g. "2025-01-15 10:30")

Example Request with Custom Fields

curl -X POST "https://email.easy.tools/api/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "john@example.com",
    "first_name": "John",
    "custom_fields": [
      {"field_key": "company", "value": "Acme Inc"},
      {"field_key": "plan", "value": "enterprise"},
      {"field_key": "is_vip", "value": true},
      {"field_key": "signup_date", "value": "2025-01-15"},
      {"field_key": "events-attended", "value": ["Webinar X", "Webinar Y"]}
    ]
  }'

Response

Success Response (201 Created)

{
  "data": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "email": "john@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+48123456789",
    "external_id": "customer_123",
    "language": "en",
    "country_code": "US",
    "lists": [
      {
        "uuid": "9f3c2a1e-8b7d-4e2f-a1c6-2d4f5e6a7b8c",
        "name": "Newsletter"
      }
    ],
    "custom_fields": [
      {
        "field_key": "company",
        "value": "Acme Inc"
      }
    ],
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Response Fields

Field	Type	Description
uuid	string	Unique identifier for the contact
email	string	Contact's email address
first_name	string|null	Contact's first name
last_name	string|null	Contact's last name
phone	string|null	Contact's phone number
external_id	string|null	External identifier for integration purposes
language	string|null	ISO 639-1 language code
country_code	string|null	ISO 3166-1 alpha-2 country code
lists	array	Contact lists the contact is subscribed to. Each entry has uuid and name.
custom_fields	array	Custom field values set on the contact. Each entry has field_key and value.
created_at	string	ISO 8601 timestamp (UTC)
updated_at	string	ISO 8601 timestamp (UTC)

Error Responses

Duplicate Contact Error (409 Conflict)

Returned when a contact with the same email already exists, or when the external_id you sent is already used by another contact. Each email and each external_id must be unique within your account. No contact is created in this case.

{
  "error": {
    "code": "DUPLICATE_RESOURCE",
    "message": "Contact with email 'john@example.com' already exists"
  }
}

{
  "error": {
    "code": "DUPLICATE_RESOURCE",
    "message": "Contact with external id 'customer_123' already exists"
  }
}

Not Found Error (404) - Contact Lists

Returned when one or more UUIDs passed in contact_lists do not exist for your account. The contact is not created in this case.

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Contact lists not found: 9f3c2a1e-8b7d-4e2f-a1c6-2d4f5e6a7b8c"
  }
}

Not Found Error (404) - Timezone

Returned when timezone_uuid does not match a timezone from List Timezones. The contact is not created in this case.

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Timezone not found"
  }
}

Validation Error (422 Unprocessable Entity)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The given data was invalid",
    "details": {
      "email": ["The email field is required."],
      "language": ["The language field must be 2 characters."],
      "contact_lists.0": ["The contact_lists.0 field must be a valid UUID."]
    }
  }
}

Custom Field Validation Error (422 Unprocessable Entity)

Returned when a value in custom_fields cannot be applied — for example an unknown field_key, a select value outside the field's options, a value of the wrong type, a text value over 255 characters, or a field that is set automatically and cannot be modified. No contact is created in this case. The specific reason is in details.custom_fields.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Custom field validation failed",
    "details": {
      "custom_fields": ["Custom field 'plan' value 'invalid_option' is not a valid option. Allowed options: free, pro, enterprise"]
    }
  }
}