The email object
Every Emails API response returns emails in one shape.
{
"id": "cmtsv6ts404hzii01dnmu4k5t",
"status": "DRAFT",
"direction": "OUTBOUND",
"subject": "Buffalo David Bitton men's multipacks, 16,300 packs",
"toEmail": "meg@example.com",
"fromEmail": "kevin@example.com",
"contactId": "cmr8dlczc00xkic01prvioybz",
"leadId": null,
"campaignId": "cmtsv6tr704hxii01xyz",
"offeringId": null,
"dealId": null,
"threadId": null,
"error": null,
"sentAt": null,
"createdAt": "2026-09-08T16:16:05.256Z",
"reviewUrl": "https://agentlyleads.com/emails/cmtsv6ts404hzii01dnmu4k5t"
}| Field | Description |
|---|---|
status | DRAFT, SCHEDULED, SENT or FAILED. API-created emails start as DRAFT. |
direction | OUTBOUND for mail you send, INBOUND for replies received into a connected mailbox. |
fromEmail | The sending identity, or null for the workspace default. |
threadId | Set when the email belongs to a conversation thread; replies share the parent's value. |
reviewUrl | Where a person opens the email in the app to review, edit, approve or send it. |
GET /api/v1/emails/:id adds bodyHtml, the linked contact and campaign, the full thread, attachments and open/click engagement. The list endpoint adds opened, opens, clicks, replied and unread per row.
Draft-first
An email created through the API is never transmitted by the create call. It is saved as a DRAFT under the contact, grouped in a campaign, and waits for one of two things: a person approves it in the app, or the integration releases it with POST /api/v1/emails/:id/send. That release needs its own scope, send:emails, so a key that only writes drafts cannot send.
Acting user
An API key belongs to the workspace, not to a person, but every draft records who wrote it and every From address belongs to someone's mailbox. Each write accepts an optional asUserEmail, the email of a workspace member to act as. When omitted, the workspace owner acts. The sending identities available to a draft are that member's connected mailboxes plus any mailbox shared with the whole workspace.