Contact Lists & Contacts

What a contact list is

A contact list is a named group of recipients with its own signup form, unsubscribe handling, and sending history. Lists are the audience you send newsletters and broadcasts to. Keep separate lists for separate intents. "Product Updates", "Billing Notices", "Beta Testers", so subscribers can opt in and out at the right granularity and your reporting stays meaningful.

For the full endpoint reference, see the Contact Lists API reference.

Create a list

curl -X POST https://api.euromail.dev/v1/contact-lists \
  -H "X-EuroMail-Api-Key: em_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product Updates",
    "description": "Monthly product news",
    "double_opt_in": true
  }'

Set double_opt_in to true (recommended, and required in practice for EU marketing mail) so new contacts must confirm via email before they are activated. See Signup Forms for the confirmation flow and GDPR Tooling for the consent record this creates.

Add a single contact

curl -X POST https://api.euromail.dev/v1/contact-lists/{list_id}/contacts \
  -H "X-EuroMail-Api-Key: em_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "metadata": { "first_name": "Aino", "plan": "pro" }
  }'

metadata is arbitrary JSON stored with the contact. Use it for personalisation tokens your templates reference (e.g. {{ first_name }}) and for segmentation.

Bulk import

To import many contacts at once, send a contacts array in the same endpoint instead of a single email:

curl -X POST https://api.euromail.dev/v1/contact-lists/{list_id}/contacts \
  -H "X-EuroMail-Api-Key: em_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "contacts": [
      { "email": "[email protected]", "metadata": { "first_name": "A" } },
      { "email": "[email protected]", "metadata": { "first_name": "B" } }
    ]
  }'

Only import contacts who consented. Importing purchased or scraped lists wrecks deliverability and breaches GDPR. EuroMail screens new accounts for sudden bursts of cold contacts.

When you import into a double_opt_in list, decide whether the contacts have already confirmed consent elsewhere. If not, run them through the confirmation flow rather than activating them directly.

List and inspect contacts

# Contacts in a list, filtered by subscription status
curl "https://api.euromail.dev/v1/contact-lists/{list_id}/contacts?status=subscribed&page=1&per_page=100" \
  -H "X-EuroMail-Api-Key: em_live_your_key_here"

# A single list with its stats
curl https://api.euromail.dev/v1/contact-lists/{list_id} \
  -H "X-EuroMail-Api-Key: em_live_your_key_here"

Contacts carry a status. pending (awaiting double opt-in confirmation), subscribed, or unsubscribed. Only subscribed contacts receive broadcasts.

Remove a contact

curl -X DELETE https://api.euromail.dev/v1/contact-lists/{list_id}/contacts/{contact_id} \
  -H "X-EuroMail-Api-Key: em_live_your_key_here"

Removing a contact deletes it from the list. To stop mailing someone while keeping the audit trail, an unsubscribe (which they trigger themselves, or you set) is usually the right action. See Suppressions.

Welcome emails

A list can automatically send a welcome email the moment a contact becomes subscribed. Configure the subject and body per list (dashboard or API); the send is deduplicated so a contact never receives two welcomes. This is the natural place to deliver a lead magnet or set expectations for cadence.

How lists relate to other features

• Signup forms feed contacts into a list. guide.
• Newsletters / broadcasts send to a list. guide.
• Unsubscribes and suppressions keep you compliant. guide.
• GDPR export/erase operate across a contact's data. guide.