Emails

Send emails, track delivery and engagement, and query email history through email use cases.

The email endpoints let you send emails through configured email use cases, retrieve email details and content, and query delivery and engagement events.

Emails are sent through use cases created with the email channel type. Each email use case is bound to an email setup with verified DNS. Delivery events - deliveries, bounces, complaints, opens, clicks - are tracked automatically after sending.

Endpoints

Method	Path	Description
POST	/v1/{workspace_id}/email/send	Send an email
GET	/v1/{workspace_id}/email	List emails
GET	/v1/{workspace_id}/email/event	List email events
GET	/v1/{workspace_id}/email/{email_id}	Get email detail
GET	/v1/{workspace_id}/email/{email_id}/body	Get email HTML body
GET	/v1/{workspace_id}/email/{email_id}/attachment/{filename}	Download attachment

Send Email

POST /v1/{workspace_id}/email/send

Send an email through an email use case. Request is multipart form data.

Form fields:

Field	Type	Required	Description
use_case_id	UUID	Yes	Email use case to send through
to_address	string (email)	Yes	Recipient email address
subject	string	Yes	Email subject (1-998 characters)
body_html	string	Yes	HTML email body (max 1 MB)
attachments	file(s)	No	Up to 5 files, max 5 MB each

Attachment rules:

• Maximum 5 attachments per email

• Maximum 5 MB per attachment

• Filenames must be non-empty, 1-255 characters, and use safe characters (no path separators or reserved names)

• Filenames must be unique within a single send

• Total assembled message must not exceed 39 MB

Response (201):

Field	Type	Description
id	UUID	Email record ID
message_id	string	Provider-assigned message correlation key
sent_at	datetime	When the email was sent
attachment_filenames	array of string	Filenames in send-time order

Errors:

• 404 - Use case not found or not an email use case

• 409 - Email setup DNS not verified

• 413 - Attachment or total message too large

• 422 - Invalid filename, empty attachment, duplicate filenames, or message rejected

Permission: Channel.send

List Emails

GET /v1/{workspace_id}/email

List emails with filters. At least one of use_case_id or setup_id is required.

Query parameters:

Parameter	Type	Required	Description
use_case_id	UUID	Conditional	Filter by use case (at least one scope required)
setup_id	UUID	Conditional	Filter by email setup (at least one scope required)
to_address	string (email)	No	Filter by recipient (repeatable, any match)
sent_after	datetime	No	Inclusive lower bound on send time
sent_before	datetime	No	Exclusive upper bound on send time
state	string	No	Filter by derived state (repeatable, any match)
limit	integer	No	Max results (1-200, default 50)
continuation_token	string	No	Opaque pagination token from prior response

State values: sent, delivered, bounced, complained, rejected

State precedence: complained > bounced > rejected > delivered > sent.

Response:

Field	Type	Description
emails	array	Email summary objects
has_more	boolean	Whether more results exist
continuation_token	string or null	Token for next page

Email summary fields:

Field	Type	Description
id	UUID	Email ID
ses_use_case_id	UUID	Use case ID
setup_id	UUID	Email setup ID
from_address	string	Sender address
to_address	string	Recipient address
subject	string	Email subject
state	string	Derived delivery state
sent_at	datetime	When sent
has_attachment	boolean	Whether attachments were included
open_count	integer	Total open events
click_count	integer	Total click events

Permission: Channel.view

List Email Events

GET /v1/{workspace_id}/email/event

List delivery and engagement events. At least one of use_case_id or setup_id is required.

Query parameters:

Parameter	Type	Required	Description
use_case_id	UUID	Conditional	Filter by use case (at least one scope required)
setup_id	UUID	Conditional	Filter by email setup (at least one scope required)
email_id	UUID	No	Filter to specific email(s) (repeatable, any match)
event_type	string	No	Filter by event type (repeatable, any match)
event_at_after	datetime	No	Inclusive lower bound on event time
event_at_before	datetime	No	Exclusive upper bound on event time
limit	integer	No	Max results (1-200, default 50)
continuation_token	string	No	Opaque pagination token from prior response

Event type values: Reject, Delivery, Bounce, Complaint, DeliveryDelay, Open, Click

Response:

Field	Type	Description
events	array	Event objects
has_more	boolean	Whether more results exist
continuation_token	string or null	Token for next page

Event fields:

Field	Type	Description
id	UUID	Event ID
email_id	UUID	Associated email ID
event_type	string	Event type
event_at	datetime	When the event occurred (provider timestamp)
received_at	datetime	When the platform recorded the event

Permission: Channel.view

Get Email

GET /v1/{workspace_id}/email/{email_id}

Get full detail of a single email.

Response:

All fields from the list summary, plus:

Field	Type	Description
message_id	string	Provider-assigned message ID
email_type	string	transactional or marketing
tier	string	Reputation tier at send time
attachment_filenames	array of string	Filenames in send-time order
delivered_at	datetime or null	First delivery confirmation
bounced_at	datetime or null	First bounce
bounce_type	string or null	Bounce classification
bounce_subtype	string or null	Bounce sub-classification
complained_at	datetime or null	First spam complaint
rejected_at	datetime or null	First rejection
delivery_delay_at	datetime or null	Most recent delivery delay
first_open_at	datetime or null	First open
last_open_at	datetime or null	Most recent open
open_count	integer	Total open events
first_click_at	datetime or null	First link click
last_click_at	datetime or null	Most recent link click
click_count	integer	Total click events
updated_at	datetime	Last update time

Errors: 404 if email not found.

Permission: Channel.view

Get Email Body

GET /v1/{workspace_id}/email/{email_id}/body

Returns the HTML body of a sent email.

Response: HTML content (text/html; charset=utf-8).

Errors: 404 if email not found.

Permission: Channel.view

Get Email Attachment

GET /v1/{workspace_id}/email/{email_id}/attachment/{filename}

Redirects (307) to a short-lived download URL for the specified attachment. The filename must match one of the filenames recorded at send time.

The download response includes a content-disposition header for browser-friendly downloading, with support for non-ASCII filenames.

Errors: 404 if email or attachment not found.

Permission: Channel.view

Delivery and Engagement Tracking

After an email is sent, the platform automatically tracks delivery and engagement events:

Event	Description
Delivery	Email accepted by the recipient's mail server
Bounce	Email bounced (includes type and subtype classification)
Complaint	Recipient reported the email as spam
Reject	Email rejected before delivery
Delivery Delay	Temporary delivery delay
Open	Recipient opened the email
Click	Recipient clicked a link in the email

Events are processed idempotently - duplicate notifications are deduplicated automatically.

Open counts reflect raw event totals (one per pixel load, subject to client-side caching). Use first_open_at and last_open_at for unique-by-email open signals. Click counts similarly reflect raw totals.

Email States

Email state is derived from delivery events with the following precedence:

1. complained - Recipient marked the email as spam (highest precedence)

2. bounced - Email bounced

3. rejected - Email rejected before delivery

4. delivered - Email delivered successfully

5. sent - Email sent but no delivery event received yet (default)

An email with both a bounce and a complaint is reported as complained.