Core concepts — the mails.ai data model

The mails.ai API is built from a small set of objects. Understanding how they relate makes the rest of the reference obvious. Every object carries a typed, prefixed ULID — the prefix tells you what kind of thing you are holding (msg_, evt_, agt_…) and the ULID sorts lexicographically by creation time.

Workspace

The workspace (wsk_) is the top-level tenant and billing root. It owns a unique slug, which becomes your sending subdomain — a workspace slugged acme sends from *.acme.mails.ai. The workspace holds the plan tier, the send-approval flag, and the suppression list. API keys belong to a workspace.

Agent

An agent (agt_) is a named sending identity inside a workspace. It has its own email address (<name>@<slug>.mails.ai), its own reputation score, and optional per-agent send limits and inbound-classification setting. Agents are the noun you address mail from and to — think of each as one persona your product operates: sarah for sales, support for tickets, notify for transactional alerts. A key may be scoped to a single agent.

Message

A message is one email. Outbound sends are msg_; inbound (received) messages are rcv_. A message carries its addresses, subject, bodies, the routing pool it was classified into, delivery state (sent, delivered, bounced, complained), and a link to its thread. You create outbound messages with POST /v1/messages; inbound messages arrive through the parsing pipeline and are read-only over the API.

Event

An event (evt_) is a typed record of something that happened — a send, a delivery, a bounce, a received reply. Events are the backbone of the reactive model: you subscribe to them with a webhook or tail them on the live stream rather than polling message state. Inbound events carry the structured signal mails.ai computes on every reply — injection_score and sender_reputation always, and intent, entities, and urgency when the receiving agent has classification enabled.

{
  "id": "evt_01J9X2K7Q8...",
  "type": "message.received",
  "agent_id": "agt_01J9...",
  "source_message_id": "rcv_01J9...",
  "injection_score": 0.02,
  "sender_reputation": 0.91,
  "intent": "schedule_demo",
  "entities": { "date": "2026-05-14", "time": "10:00" },
  "urgency": 0.8,
  "created_at": "2026-06-19T17:40:00.000Z"
}

Thread

A thread (thrd_) groups a conversation. mails.ai reconstructs threading from In-Reply-To / References headers, so a reply to a message you sent lands on the same thread_id. Threads let you fetch a whole back-and-forth and carry an open / closed / archived status.

Draft

A draft (dft_) is a composed message that has not sent yet. Create a draft, edit it, then send it with POST /v1/drafts/{id}/send— immediately, or scheduled for a future send_at. Drafts are how you stage a send for review or schedule one without holding the content in your own store.

Webhook

A webhook (whe_) is an HTTPS endpoint you register to receive events as they happen. You choose which event types to subscribe to; deliveries are HMAC-signed, retried with backoff, and logged so you can inspect and replay them. See webhooks for signature verification.

Suppression

A suppression (sup_) is a blocked recipient. Hard bounces, complaints, and unsubscribes add an address to the workspace suppression list, and any send to a suppressed address returns 422 recipient_suppressed rather than firing. Suppression protects your reputation automatically; you can also explicitly allow an address back with a consent attestation.

Reputation

Reputationis a per-agent score from 0 to 1, computed from real engagement — sends, replies, bounces, and complaints over a trailing window. It rides along on every inbound event as sender_reputation(the score of whoever wrote to you), and you can query your own agents’ reputation directly. Low reputation is the signal that an identity is being treated as spam by the network; high reputation is what keeps an agent on the clean pool.

How they fit together

A workspace holds one or more agents. An agent sends a message, which opens (or continues) a thread and emits a message.sent event. When the recipient replies, mails.ai parses the inbound message, computes its signal, and emits a message.received eventon the same thread — delivered to your webhook and tailable on the stream. Bounces and complaints add a suppression and move the agent’s reputation. Every call is authorized by an API key scoped to the workspace.