Key Concepts

This section defines the entities you work with through the API, how they relate to each other, and the statuses and lifecycles that govern them. If you only have five minutes, read Messages first: everything else on the platform exists to produce, address, fund, or track messages.

Every entity belongs to your account. An API key only sees and changes its own account’s data, and an id that belongs to another account answers 404.

Sending

  • Message — one email to one recipient, created by a transactional send, an OTP request, a campaign, an automation step, or a template test send; it carries a delivery status and an event history. See Messages.
  • Sending domain — a domain or subdomain you register, connect to a mail provider (ses or kumomta), and verify through DNS; every message is sent from a verified domain. See Domains, sender profiles & warmup.
  • Sender profile — a mailbox definition (local_part, display name, Reply-To) that becomes the From address <local_part>@<sending domain>; exactly one profile is your default. See Domains, sender profiles & warmup.
  • Sender route — a mapping from a send type (blast, automation, transactional, otp) to the sender profile that type uses. See Domains, sender profiles & warmup.
  • Warmup — the daily volume ramp a newly verified domain follows. See Domains, sender profiles & warmup.

Content

  • Template — reusable email content with a message class (marketing, transactional, critical) and a status that decides whether it can send. See Templates.
  • Template version — an immutable snapshot of a template’s content with its own moderation verdict; every content edit creates a new one. See Templates.
  • Asset — an image you upload once and reference from template content by its CDN URL. See Upload an image asset.

Audience

  • Contact — a recipient record: email, name, custom field values, consent data, and a subscription status. See Contacts & Audiences.
  • Custom field — an account-defined contact attribute (string, number, date, bool, enum) usable in templates and segment filters. See Contacts & Audiences.
  • List — a static set of contacts with explicit membership. See Contacts & Audiences.
  • Segment — a dynamic set of contacts defined by a filter and evaluated each time it is used. See Contacts & Audiences.
  • Custom event — a named, timestamped fact about a contact that you record with POST /events. See Contacts & Audiences.
  • Import job — the asynchronous job that processes a bulk CSV or XLSX contact upload. See Contacts & Audiences.
  • Suppression entry — an address the platform refuses to mail because of an unsubscribe, a bounce, a complaint, or a manual block. See Suppressions.

Campaigns and journeys

  • Campaign — a one-time send (blast) to an audience built from lists, segments, or an uploaded file, or the container of an automation. See Campaigns.
  • Recipient upload — an ad-hoc recipient file used in one campaign’s audience without creating contacts. See Campaigns.
  • Automation — a campaign of type automation: a trigger plus a graph of send, wait, branch and exit steps that contacts move through over time. See Automations.
  • Enrollment — one contact’s progress through one automation. See Automations.

Account

  • Credit balance — the prepaid balance that funds sending at one credit per message, with optional protected minimums and credit lines. See Billing & Credits.
  • Invoice — the record of a credit purchase. See Billing & Credits.
  • Webhook subscription — an HTTPS endpoint that receives delivery, engagement and unsubscribe events. See Webhooks & Events.

How they relate

A contact can belong to any number of lists and match any number of segments, but membership never overrides the suppression list or the contact’s own status. A campaign combines a marketing template, a verified sending domain, an optional sender profile, and an audience; at launch it pins one template version and produces one message per eligible recipient. An automation is a campaign whose recipients arrive one at a time as enrollments, and it produces a message each time an enrollment reaches a send step. Transactional and OTP sends produce messages directly from an API call. Whatever produced it, every message goes out from a verified domain within that domain’s warmup allowance, uses a From address resolved from a sender profile, costs one credit, and moves through the message lifecycle that webhooks report on.

Where to go next