API reference

Queues a transactional email. Production requests must attest the business trigger and recipient relationship in `transactional`. Marketing email must use the campaign API so audience consent, suppression, sender identity, and unsubscribe controls are enforced. The `from` domain must be a verified transactional sending domain. Pass an `Idempotency-Key` header to make retries safe: the same key and body replays the original message (200, `idempotent_replay: true`, also under concurrent retries); the same key with a different body is refused with 409 `idempotency_key_reused`. Keys do not expire. Set `expires_at` or `ttl_seconds` so mail that cannot be handed to the provider in time fails with reason `expired` instead of arriving late.

{
  "from": "Meetumo <hello@send.meetumo.ai>",
  "to": "user@example.com",
  "subject": "Welcome to Meetumo",
  "html": "<p>Thanks for signing up.</p>",
  "transactional": {
    "category": "account",
    "trigger_id": "signup_01j...",
    "recipient_relationship": "account_holder"
  }
}

{
  "id": "msg_01j…",
  "status": "queued"
}

Resend-compatible batch. The body is a JSON array of 1-100 objects, each exactly the `POST /v1/emails` body and validated by the same rules. Validation is all-or-nothing: an invalid item rejects the whole batch with its `index` and nothing is queued. With an `Idempotency-Key` header (max 250 characters) item i uses the key `<key>:<i>`, so retrying the whole batch replays every item; a retried batch whose item i changed is refused with 409 and that `index`.

{
  "data": [
    {
      "id": "msg_01j…",
      "status": "queued"
    },
    {
      "id": "msg_01k…",
      "status": "queued"
    }
  ]
}

Read-only, send-scoped check of workspace approval and an active verified transactional identity. Does not send an email or expose message content. Returns 503 when sending is unavailable.

Returns the DNS records (DKIM, SPF, DMARC, MAIL FROM) to publish. eimailar re-checks them automatically. Follow the dashboard setup guide to complete domain activation.

{
  "domain": "send.meetumo.ai",
  "stream": "transactional"
}

Requires contacts scope. Identify the person by contactId or email. Omit goalId to record against every objective with this event type. Exact duplicate externalEventId is idempotent; changed identity, time or value is refused. Times before objective creation, older than 90 days or more than five minutes ahead are refused. No sending authority is created.

Every contact carries a consent basis. `double_opt_in` creates a pending contact and sends a confirmation email. Direct single opt-in and customer soft opt-in require a bounded attestation, source, and capture time before marketing eligibility is recorded.

{
  "email": "user@example.com",
  "attributes": {
    "name": "Ada",
    "company": "Acme"
  },
  "list_ids": [
    "lst_01j…"
  ],
  "consent": {
    "method": "single_opt_in",
    "evidence": {
      "attested": true,
      "source": "Product signup form",
      "captured_at": "2026-08-06T12:00:00Z",
      "policy_version": "2026-08"
    }
  }
}

Requires explicit consent attestation. Reuses existing active contacts without changing attributes, records consent and joins the selected list. Inactive contacts remain unchanged. Skips suppressed, invalid and repeated addresses. Returns counts and a durable import report ID in the X-Eimailar-Import-Id header.

{
  "contacts": [
    {
      "email": "a@example.com",
      "attributes": {
        "name": "A"
      }
    }
  ],
  "list_id": "lst_01j…",
  "consent": {
    "attested": true,
    "evidence": {
      "source": "Event registration export",
      "captured_at": "2026-08-06T12:00:00Z",
      "policy_version": "2026-08"
    }
  }
}

{
  "created": 2,
  "existing": 0,
  "suppressed": 1,
  "invalid": 0,
  "duplicates": 1
}

Retry-safe contact ingestion by normalized email. Merges attributes and list memberships, but never reactivates unsubscribed, bounced, complained, or suppressed contacts.

{
  "email": "user@example.com",
  "attributes": {
    "name": "Ada",
    "plan": "pro"
  },
  "source": "product-signup",
  "list_ids": [
    "lst_01j…"
  ],
  "consent": {
    "method": "single_opt_in",
    "evidence": {
      "attested": true,
      "source": "Product signup form",
      "captured_at": "2026-08-06T12:00:00Z",
      "policy_version": "2026-08"
    }
  }
}

Returns a connection-scoped secret exactly once. It cannot send email or access any other API resource.

{
  "name": "Website signups",
  "source": "website-signup",
  "list_id": "lst_01j…",
  "consent": {
    "method": "double_opt_in",
    "scope": "marketing"
  },
  "mapping": {
    "email": "data.customer.email",
    "event_id": "event.id",
    "attributes": {
      "first_name": "data.customer.first_name",
      "plan": "data.plan"
    }
  }
}

Returns a source-scoped HMAC signing secret exactly once. Identity is scoped by tenant, source, and external user ID.

{
  "name": "Partner product",
  "source": "partner_product",
  "feedback_url": "https://partner.example/hooks/eimailar"
}

Source-neutral HMAC receiver. Sign `<unix-seconds>.<raw-body>` and keep event IDs stable for safe retries.

{
  "version": "1.0",
  "event_id": "evt_01",
  "event_type": "user.registered",
  "occurred_at": "2026-08-01T12:00:00.000Z",
  "source": "partner_product",
  "external_user_id": "user_123",
  "subject": {
    "type": "user"
  },
  "roles": [
    "registered_user"
  ],
  "data": {
    "email": "person@example.com"
  },
  "trace_id": "trace_01",
  "suppress_automation": false,
  "allow_send": true
}

Public ingestion endpoint for one connection. Send its one-time secret as `X-Eimailar-Secret` (or a Bearer token). `X-Eimailar-Event-Id` can override the mapped event ID for replay protection.

{
  "event": {
    "id": "signup_123"
  },
  "data": {
    "customer": {
      "email": "user@example.com",
      "first_name": "Ada"
    }
  }
}

Preserves contacts, membership, double opt-in and campaign references. Requires name; an omitted description is preserved and null clears it. Conflicting list names return 409.

{
  "name": "Product updates",
  "description": "Subscribers to product news"
}

Preserves contacts. Refuses deletion while a campaign, segment rule or automation trigger/action references the list, with workspace-scoped dependencies in the response.

Returns the matching count and a sample without saving.

{
  "count": 128,
  "sample": [
    {
      "email": "a@x.com",
      "status": "active"
    }
  ]
}

Requires campaigns scope. Sources must belong to the workspace. Attribution configuration is fixed after creation.

Audience is one or more lists and/or a segment. Content is inline html/text.

{
  "name": "July update",
  "subject": "Hi {{name}} — what's new",
  "from": "Meetumo <news@mail.meetumo.ai>",
  "audience": {
    "list_ids": [
      "lst_01j…"
    ],
    "segment_id": "seg_01j…"
  },
  "html": "<p>Big news, {{name}}!</p>"
}

Materializes the audience and starts the resumable send.

Preflight-validates the campaign and schedules it for a future instant. Re-scheduling an already-scheduled campaign replaces the time.

{
  "send_at": "2026-09-01T14:00:00Z"
}

Returns the campaign to draft and drops the pending start. 409 unless the campaign is scheduled.

A trigger plus linear steps (wait / send). Activate it to enroll matching contacts.

{
  "name": "Welcome series",
  "trigger": {
    "kind": "list_joined",
    "listId": "lst_01j…"
  },
  "steps": [
    {
      "kind": "send",
      "from": "hello@mail.meetumo.ai",
      "subject": "Welcome {{name}}",
      "html": "<p>Hi {{name}}</p>"
    },
    {
      "kind": "wait",
      "minutes": 1440
    },
    {
      "kind": "send",
      "from": "hello@mail.meetumo.ai",
      "subject": "Getting started",
      "html": "<p>…</p>"
    }
  ]
}

Provide a block `design`; eimailar renders it to html and text.

Returns a signing secret once. Each delivery is signed with `eimailar-signature: t=<unix>,v1=<hmac-sha256>` over `<t>.<body>`. The body is `{ id, type, created_at, data }`; `id` is a stable event id, identical on every retry and endpoint, also sent as the `eimailar-event-id` header (with `eimailar-event-type`) so receivers can deduplicate. Event types: `email.delivered`, `email.bounced`, `email.complained`, `email.opened`, `email.clicked`, and for transactional API mail `email.failed` (provider rejection, final soft bounce, expiry, domain or workspace gate; `data.reason`), `email.suppressed` (send-time suppression; `data.reason`) and `email.delivery_delayed` (SES DeliveryDelay; `data.delay`). Use `*` for all.

{
  "url": "https://api.yourservice.com/eimailar-hook",
  "event_types": [
    "email.bounced",
    "email.complained"
  ]
}