Contact API Reference

Endpoint

POST https://api.emailelement.com/api/contactList/{listId}/Contacts?overwriteExisting={true|false}

Authentication

All requests require the x-api-key header with a valid API key that has Contact API permission enabled.

x-api-key: YOUR_API_KEY

URL Parameters

Query Parameters

Request Body

{
  "data": [
    {
      "Email": "john@example.com",
      "First Name": "John",
      "Last Name": "Doe",
      "Age": 30,
      "Date Of Birth": "1995-06-15T00:00:00.000Z"
    }
  ],
  "requiredFields": ["First Name"]
}

Fields

Contact Object Fields

The Email field is always required. All other fields are optional. Use the exact field names as they appear in your Contact List (including spaces).

Standard fields:

Custom fields: Any custom fields defined on the Contact List can be included using the exact field name as the key.

Example: Multiple Contacts with Required Fields

{
  "data": [
    {
      "Email": "jane@example.com",
      "First Name": "Jane",
      "Last Name": "Smith",
      "City": "New York"
    },
    {
      "Email": "bob@example.com",
      "First Name": "Bob",
      "Last Name": "Johnson"
    }
  ],
  "requiredFields": ["First Name", "Last Name"]
}

Responses

Success (200 OK)

All contacts were accepted:

{
  "succeeded": true,
  "data": [
    {
      "Email": "jane@example.com",
      "First Name": "Jane",
      "Last Name": "Smith",
      "City": "New York"
    },
    {
      "Email": "bob@example.com",
      "First Name": "Bob",
      "Last Name": "Johnson"
    }
  ],
  "messages": []
}

Validation Error (200 with errors)

One or more contacts failed validation (e.g., missing required fields):

{
  "succeeded": false,
  "data": null,
  "messages": [
    {
      "emailAddress": "jane@example.com",
      "errorMessage": "The following required fields are missing: First Name. The contact with email jane@example.com will not be added."
    }
  ]
}

Unauthorized (401)

Invalid or missing API key:

{
  "Data": null,
  "Succeeded": false,
  "Message": "Invalid ApiKey"
}

Batch Operations

• Send multiple contacts in a single request via the data array
• For large imports, split into batches
• Use overwriteExisting=true to update existing contacts by email match
• Use requiredFields to enforce data quality — contacts missing required fields are rejected with a descriptive error

Custom Fields

• Custom fields are created in the EmailElement UI under Contact Lists > select list > Custom Fields, or via the API Documentation page using + Add New Custom Field
• Use the exact field name (including spaces) as the JSON key in the contact object
• Custom field values can be strings, numbers, or dates depending on the field type

Rate Limits

• 100 requests per minute per API key
• 429 status code returned when limit is exceeded
• Include a retry-after delay when receiving 429 responses