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)
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")
contact_lists	array of strings	No	UUIDs of contact lists the new contact should be subscribed to

note

When contact_lists is provided, all list UUIDs must belong to your account - otherwise the request is rejected and no contact is created. Any list from which the contact (matched by email) was previously unsubscribed is silently skipped; the contact will still be created and added to the remaining lists.

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"
    ]
  }'

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",
    "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
created_at	string	ISO 8601 timestamp (UTC)
updated_at	string	ISO 8601 timestamp (UTC)

Error Responses

Duplicate Email Error (409 Conflict)

Returned when a contact with the same email already exists.

{
  "error": {
    "code": "DUPLICATE_RESOURCE",
    "message": "Contact with email 'john@example.com' 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"
  }
}

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 must be 2 characters."],
      "contact_lists.0": ["The contact_lists.0 must be a valid UUID."]
    }
  }
}