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 goes into your agents’ addresses — a workspace slugged acme sends from *.acme@send.mails.ai and receives at *.acme@in.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. Its address in the API is <name>@<slug>.mails.ai, which is not an inbox: its mail goes out from <name>.<slug>@send.mails.ai and it receives mail at <name>.<slug>@in.mails.ai, with 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. Sent messages are msg_; inbound (received) messages are rcv_. A message carries its addresses, subject, bodies, delivery state (sent, delivered, bounced, complained), and a link to its thread. You create 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 inbound message within your plan’s limits — injection_score and sender_reputation always, and intent, entities, and urgency read from the message only when it is first contact and the receiving agent has classification enabled (fixed values otherwise).

{
  "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 and complaints suppress an address for every workspace, an unsubscribe only for yours, 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

Reputation is a per-agent score from 0 to 1, computed from real engagement — sends, replies, bounces, and complaints over a trailing window. A different score rides along on every inbound event for mail within your plan’s limits as sender_reputation (a trust estimate for 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.

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 reply.received event on 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.