Resource reference

Every core resource over plain REST: lists, subscribers (single and bulk), segments, campaigns with downloadable logs, sending domains, templates, your brand profile, account usage meters, and a unified analytics event feed. Scope names in each section refer to API key scopes.

Lists

Mailing lists are the primary container for subscribers. Each list has a default sender identity and a set of custom fields, which you add with the add-field sub-route. Scope: audiences (implied by contacts).

# Create a list
curl -X POST https://emailflow.ai/api/v1/lists \
  -H "Authorization: Bearer efa_YOUR_KEY" \
  -d name="Newsletter" \
  -d from_name="Acme" \
  -d from_email="hi@acme.com" \
  -d contact[company]="Acme Inc." \
  -d contact[address_1]="1 Market St" \
  -d contact[city]="San Francisco" \
  -d contact[zip]="94105" \
  -d contact[phone]="+1 555 0100" \
  -d contact[country_id]=1 \
  -d contact[email]="hi@acme.com"

# Response
{
  "status": 1,
  "message": "List has been created!",
  "list_uid": "ab12cd34ef"
}

Add a custom field to that list:

curl -X POST https://emailflow.ai/api/v1/lists/{uid}/add-field \
  -H "Authorization: Bearer efa_YOUR_KEY" \
  -d type=text \
  -d label="First name" \
  -d tag=FIRST_NAME

Subscribers

Subscribers belong to a list and carry custom field values, tags, and a status of subscribed, unsubscribed, or unconfirmed. Custom fields are passed as uppercase parameters (FIRST_NAME, LAST_NAME, …) matching your list's field configuration. Scope: audiences (implied by contacts).

Single subscriber operations

# Add a subscriber with custom fields and tags
curl -X POST https://emailflow.ai/api/v1/subscribers \
  -H "Authorization: Bearer efa_YOUR_KEY" \
  -d list_uid=ab12cd34ef \
  -d EMAIL=alice@example.com \
  -d FIRST_NAME=Alice \
  -d tag=vip,newsletter \
  -d status=subscribed

Bulk import and delete

Import or remove many subscribers at once. The synchronous endpoints apply rows inline and return per-row results; JSON payloads accept at most 1,000 rows per request (a larger payload returns 422). For bigger imports, upload a CSV to the asynchronous endpoint, which queues the work and returns a job you poll for progress. Write endpoints carry the batch rate-limit class (10 requests per minute) — see rate limits.

Callers authenticating with a scoped efa_ key receive the aligned partial-success shape {processed, created, updated, failed, errors: [{index, email, code, message}], warnings: [...]}; legacy-token callers keep the original {list_uid, received, inserted, updated, failed, batch_id, errors} shape unchanged.

# Synchronous bulk import (JSON body)
curl -X POST "https://emailflow.ai/api/v1/lists/{list_uid}/subscribers/bulk" \
  -H "Authorization: Bearer efa_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "overwrite",
    "subscribers": [
      { "EMAIL": "alice@example.com", "FIRST_NAME": "Alice", "tags": ["vip"] },
      { "EMAIL": "bob@example.com",   "FIRST_NAME": "Bob",   "status": "subscribed" }
    ]
  }'

# Response (scoped efa_ key)
{
  "processed": 2,
  "created": 1,
  "updated": 1,
  "failed": 0,
  "errors": [],
  "warnings": []
}

For large or untrusted inputs, queue the job and poll it:

# Queue an async import, then poll
curl -X POST "https://emailflow.ai/api/v1/lists/{list_uid}/subscribers/bulk/async" \
  -H "Authorization: Bearer efa_YOUR_KEY" \
  -F "file=@subscribers.csv" \
  -F 'mapping={"Email":"EMAIL","First Name":"FIRST_NAME"}' \
  -F "mode=overwrite"

# 202 Accepted
{ "job_uid": "job_77aa", "status": "queued", "status_url": "...", "cancel_url": "..." }

# Poll
curl "https://emailflow.ai/api/v1/import-jobs/job_77aa" \
  -H "Authorization: Bearer efa_YOUR_KEY"

Segments

Segments are saved filters over a list's subscribers, built from conditions on fields, tags, verification state, engagement dates, and signup date. Conditions use the same operators the in-app segment builder offers; an invalid operator for a condition type is rejected with a validation error. Scope: contacts.

# Create a segment of recently active Gmail contacts
curl -X POST "https://emailflow.ai/api/v1/lists/{list_uid}/segments" \
  -H "Authorization: Bearer efa_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Active Gmail readers",
    "matching": "any",
    "conditions": [
      { "type": "field", "field_uid": "EMAIL_FIELD_UID", "operator": "contains", "value": "@gmail.com" },
      { "type": "last_open_email", "operator": "last_open_email_less_than_days", "value": "7" }
    ]
  }'

Campaigns

Campaigns are the unit of sending. Create one with HTML content and tracking flags, move it through run / pause / resume, then download per-event logs as CSV. See the campaigns guide for the full picture. Scope: sends (implied by emails).

Managing campaigns

# Create then run a campaign
curl -X POST https://emailflow.ai/api/v1/campaigns \
  -H "Authorization: Bearer efa_YOUR_KEY" \
  -d list_uid=ab12cd34ef \
  -d name="Spring sale" \
  -d subject="20% off this week" \
  -d from_email=hi@acme.com \
  -d from_name="Acme" \
  -d track_open=true \
  -d track_click=true \
  --data-urlencode 'html=<p>Hello!</p>'

curl -X POST https://emailflow.ai/api/v1/campaigns/{uid}/run \
  -H "Authorization: Bearer efa_YOUR_KEY"

Log downloads

Each log endpoint streams a CSV for one event type. See reports and logs for how this data maps to the in-app reports. For a streaming JSON feed of the same events, use the analytics event feed below; to be notified the moment events happen, use webhooks.

Sending domains

Register and verify the domains you send from. Creating a domain returns the DNS records to publish (an ownership record, DKIM records, and SPF); call verify after publishing to re-poll status. Depending on your plan's sending configuration, records are either the managed CNAME set or TXT-based local DKIM — the response reflects whichever mode applies. Internationalized domains are stored in punycode. Scope: domains (implied by emails).

# Register a domain, publish the returned records, then verify
curl -X POST https://emailflow.ai/api/v1/domains \
  -H "Authorization: Bearer efa_YOUR_KEY" \
  -d domain=mail.acme.com

curl -X POST https://emailflow.ai/api/v1/domains/{uid}/verify \
  -H "Authorization: Bearer efa_YOUR_KEY"

Templates

Read access to your saved email templates. source tells you where each came from: gallery (started from the template gallery), imported (ZIP or HTML upload), ai (built in the AI builder), or api (created through the AI generation API). Pass include=html on the detail endpoint to receive the full HTML. Scope: templates (implied by emails).

Brand profile

Your account's brand profile — company identity, colors, fonts, and logo — as one read-only resource. Poll crawl_status after starting a brand scan in the app (idle → scraping → analyzing → importing_logo → extracting_colors → completed or failed). Scope: brand.

Usage

One consolidated snapshot of your plan quotas and credits: per-resource used/limit meters (lists, campaigns, subscribers, automations, sending domains, users, API keys) and per-credit granted/used/remaining balances (email sends, contact verifications, AI generations). Unlimited grants report "unlimited": true. Scope: usage.

Analytics events

A unified, newest-first feed of every delivery event across your account: sent, failed, open, click, bounce, feedback, and unsubscribe. Each event carries the campaign, the subscriber email, and type-specific metadata (clicked URL, bounce type, IP and user agent). Filters compose; results paginate with an opaque cursor returned in meta.next_cursor. Scope: analytics.

# Recent opens and clicks for one campaign
curl "https://emailflow.ai/api/v1/analytics/events?type[]=open&type[]=click&campaign_uid={uid}" \
  -H "Authorization: Bearer efa_YOUR_KEY"

# Response
{
  "data": [
    {
      "type": "click",
      "occurred_at": "2026-06-12T09:15:02+00:00",
      "campaign_uid": "ab12cd34ef",
      "campaign_name": "Spring sale",
      "subscriber_email": "alice@example.com",
      "meta": { "url": "https://acme.com/promo", "ip_address": "198.51.100.7", "user_agent": "..." }
    }
  ],
  "meta": { "next_cursor": "eyJ0IjoiMjAyNi0wNi0xMiAw..." }
}

Notifications

If you operate your own delivery pipeline, push delivery feedback back into EmailFlow AI so reports and suppression stay accurate. Report hard bounces and spam or abuse complaints against the original message id.

curl -X POST https://emailflow.ai/api/v1/notification/bounce \
  -H "Authorization: Bearer efa_YOUR_KEY" \
  -d message_id="2016374...@example.com" \
  -d description="550 mailbox not found"