Contact API Walkthrough

Prerequisites

• An EmailElement account with at least one Contact List
• An API key with Contact API permission set to Full Access
• An API client such as Postman, cURL, or your application code

Step 1: Find Your Contact List ID

1. Navigate to Contact Lists from the sidebar

   

2. Find the list you want to add contacts to

3. The ID is in the left column of the grid

   

4. Copy it — it goes in the API URL

Step 2: Generate an API Key

1. Navigate to Account > API Keys

   

   

2. Click Add

   

3. Enter a name for the key, for example "Contact API - Production"

   

4. Set the Contact API permission to Full Access

   

5. Set the other permissions as needed

6. Click Create

   

7. Click Copy. The key stays available — you can return to Account > API Keys and copy it again later

   

   

8. Store it somewhere safe and do not share it

Step 3: Use the API Documentation Generator

1. Navigate to API Documentation from the sidebar

   

2. Select Contact API

3. Pick the tab for the call you want. POST (V2) and GET (V2) are the current ones. The V1 tabs are marked deprecated and are there for existing integrations

   

   

   

4. Under Fields, tick the fields to include. Email is always required and cannot be unticked

   

   

5. Under Required Fields, tick any field that must carry a value. A contact missing one is rejected

6. Click + Add New Custom Field to create a field without leaving the page

   

   

   

   

   

7. The generator builds the Request URL, and for POST the Request Body, as you tick

   

   

8. Copy them

   

9. Each tab lists every response code that call can return, with an example body. Read that list before writing your error handling

Step 4: Configure Your API Client

Using Postman

1. Create a new request

   

2. Set the method to POST

   

3. Paste the Request URL from the generator

   

4. Replace YOUR_LIST_ID with your Contact List ID

   

5. On the Headers tab add key x-api-key with your API key as the value

   

   

   

   

6. On the Body tab choose Raw, set the type to JSON, and paste the Request Body

   

   

   

7. Replace the placeholder values with real contact data

   

Using cURL

curl -X POST "https://api.emailelement.com/api/ContactList/YOUR_LIST_ID/Contacts?overwriteExisting=true"   -H "x-api-key: YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "data": [
      {
        "Email": "jane.doe@example.com",
        "First Name": "Jane",
        "Last Name": "Doe"
      }
    ],
    "requiredFields": ["First Name"]
  }'

The field names are the ones on your Contact List, spaces and all. They are not camelCase, in the request or in the response.

V1 takes a different body — the contact array on its own, with no data wrapper and no requiredFields. Moving only the list id in the path is not enough to switch versions.

Step 5: Send the Request and Check the Result

1. Send the request

   

2. Branch on the HTTP status code, not on the body. See CONTACT_API_REFERENCE.md for why

   

3. On a 200, compare the data array in the response against what you sent. That array is the list of contacts that were actually stored. A 200 can still have dropped some

4. Read messages for the reason behind anything that was dropped

5. Navigate to Contact Lists and check the Record Count went up

   

   

Adding Contacts in Bulk

• The POST call takes an array of contacts in one request
• Contacts are validated as a batch. More than 10% failing rejects the whole request with a 400 and adds nothing. 10% or fewer failing gives a 200, adds the rest, and reports the failures
• A request of fewer than ten contacts is all or nothing, because one failure already exceeds 10%
• overwriteExisting defaults to true on all four routes, V1 and V2, so a contact already on the list has their data updated. Send overwriteExisting=false to leave existing contacts alone

Common Errors

There is no 404 and no 429 on this API. An unknown list id comes back as a 400.