Emails

Every Emails endpoint.

GET/v1/analytics

Aggregate delivery, engagement and per-tag analytics

Delivery and engagement totals over the trailing `days` (default 7), plus a daily `time_series` and a `by_tag` breakdown keyed on `EmailSend.tag`.

Auth: apiKey or jwt

Parameters

Name	In	Required	Description
days	query	optional

Responses

200 : Default Response

Field	Type	Required
by_tag	array	required
by_tag[].bounced	number	required
by_tag[].clicked	number	required
by_tag[].opened	number	required
by_tag[].sent	number	required
by_tag[].tag	string	required
event_totals.bounced	number	optional
event_totals.clicked	number	optional
event_totals.delayed	number	optional
event_totals.failed	number	optional
event_totals.held	number	optional
event_totals.opened	number	optional
event_totals.sent	number	optional
summary.bounce_rate	number	required
summary.click_rate	number	required
summary.delivery_rate	number	required
summary.open_rate	number	required
summary.total_bounced	number	required
summary.total_clicked	number	required
summary.total_delivered	number	required
summary.total_opened	number	required
summary.total_sent	number	required
time_series	array	required
time_series[].bounced	number	optional
time_series[].clicked	number	optional
time_series[].date	string	required
time_series[].delayed	number	optional
time_series[].delivered	number	optional
time_series[].failed	number	optional
time_series[].held	number	optional
time_series[].opened	number	optional
time_series[].sent	number	optional

curl

curl https://api.zsender.io/v1/analytics \
  -H "Authorization: Bearer $ZSENDER_API_KEY"

GET/v1/emails

List sent emails

Messages this tenant sent, newest first. `search` is case-insensitive and matches a WHOLE recipient address, or a substring of the sender or the subject; `tag` is an exact match on the tag set at send time.

Auth: apiKey or jwt

Parameters

Name	In	Required
page	query	optional
limit	query	optional
search	query	optional
tag	query	optional

Responses

200 : Default Response

Field	Type	Required
data	array	required
data[].created_at	string	required · nullable
data[].event_count	number	required
data[].from	string	required
data[].id	string	required
data[].last_event	string	required · nullable
data[].message_id	string	required
data[].mode	string	required
data[].subject	string	required · nullable
data[].tag	string	required · nullable
data[].to	array	required
data[].to[]	string	optional
pagination.limit	number	required
pagination.page	number	required
pagination.pages	number	required
pagination.total	number	required

curl

curl https://api.zsender.io/v1/emails \
  -H "Authorization: Bearer $ZSENDER_API_KEY"

GET/v1/emails/{id}

Get one sent email

The stored record for one message this tenant sent, by its `id` from the send response. `404` if the id is unknown or belongs to another tenant.

Auth: apiKey or jwt

Parameters

Name	In	Required	Description
id	path	required

Responses

200 : Default Response

Field	Type	Required
created_at	string	required · nullable
events	array	required
events[].event_type	string	required
events[].id	string	required
events[].timestamp	string	required · nullable
from	string	required
id	string	required
last_event	string	required · nullable
message_id	string	required
subject	string	required · nullable
to	array	required
to[]	string	optional

curl

curl https://api.zsender.io/v1/emails/{id} \
  -H "Authorization: Bearer $ZSENDER_API_KEY"

GET/v1/emails/{id}/events

Delivery events and SMTP attempts

`attempts[]` is the per-recipient SMTP transcript (`status`, `smtp_output`, `details`, `sent_with_ssl`, `duration_ms`, `at`) parsed from the mail server's stored delivery events, plus `spam_status`. No new call to the mail server is made.

Auth: apiKey or jwt

Parameters

Name	In	Required	Description
id	path	required

Responses

200 : Default Response

Field	Type	Required
attempts	array	required
attempts[].at	string	required
attempts[].details	string	required · nullable
attempts[].duration_ms	number	required · nullable
attempts[].sent_with_ssl	boolean	required
attempts[].smtp_output	string	required · nullable
attempts[].status	string	required · nullable
events	array	required
events[].event_type	string	required
events[].id	string	required
events[].timestamp	string	required · nullable
spam_status	string	required · nullable

curl

curl https://api.zsender.io/v1/emails/{id}/events \
  -H "Authorization: Bearer $ZSENDER_API_KEY"

GET/v1/emails/{id}/inspect

Inspect raw MIME, headers and spam result

Live-fetches raw MIME, headers, inspection and spam score straight from the mail server for one `recipient` of the message. `409` when no stored message id exists for that recipient yet.

Auth: apiKey or jwt

Parameters

Name	In	Required	Description
recipient	query	optional
id	path	required

Responses

200 : Default Response

Field	Type	Required
headers	object	required
inspection	object	required
raw_message	string	required · nullable
recipient	string	required
spam_checks	object	required
spam_status	string	required · nullable

curl

curl https://api.zsender.io/v1/emails/{id}/inspect \
  -H "Authorization: Bearer $ZSENDER_API_KEY"

GET/v1/emails/received

List received mail

Metadata only, no text/html/attachment bytes. `to`/`from` are exact/contains filters; `since`/`until` filter on receipt time and accept either a date (`YYYY-MM-DD`, interpreted as midnight UTC) or a full RFC 3339 timestamp with an offset (e.g. `2026-01-01T00:00:00Z`).

Auth: apiKey or jwt

Parameters

Name	In	Required
page	query	optional
limit	query	optional
to	query	optional
from	query	optional
since	query	optional
until	query	optional

Responses

200 : Default Response

Field	Type	Required
data	array	required
data[].attachment_count	number	required
data[].bcc	array	required
data[].bcc[]	string	optional
data[].bounce	boolean	required
data[].cc	array	required
data[].cc[]	string	optional
data[].date	string	required · nullable
data[].from	string	required
data[].from_address	string	required
data[].id	string	required
data[].in_reply_to	string	required · nullable
data[].message_id	string	required
data[].received_at	string	required · nullable
data[].received_for	array	required
data[].received_for[]	string	optional
data[].references	array	required
data[].references[]	string	optional
data[].size	number	required
data[].spam_status	string	required
data[].subject	string	required
data[].to	array	required
data[].to[]	string	optional
pagination.limit	number	required
pagination.page	number	required
pagination.pages	number	required
pagination.total	number	required

curl

curl https://api.zsender.io/v1/emails/received \
  -H "Authorization: Bearer $ZSENDER_API_KEY"

GET/v1/emails/received/{id}

Get one received message

Includes `text`/`html` body and attachment metadata (`filename`, content type, size, not the bytes; fetch those from the attachment endpoint). `404` for an unknown or cross-tenant id.

Auth: apiKey or jwt

Parameters

Name	In	Required	Description
id	path	required

Responses

200 : Default Response

Field	Type	Required
attachments	array	required
attachments[].content_type	string	required
attachments[].filename	string	required
attachments[].id	string	required
attachments[].size	number	required
auto_submitted	string	required · nullable
bcc	array	required
bcc[]	string	optional
bounce	boolean	required
cc	array	required
cc[]	string	optional
date	string	required · nullable
from	string	required
from_address	string	required
html	string	required · nullable
id	string	required
in_reply_to	string	required · nullable
message_id	string	required
received_at	string	required · nullable
received_for	array	required
received_for[]	string	optional
references	array	required
references[]	string	optional
size	number	required
spam_status	string	required
subject	string	required
text	string	required · nullable
to	array	required
to[]	string	optional

curl

curl https://api.zsender.io/v1/emails/received/{id} \
  -H "Authorization: Bearer $ZSENDER_API_KEY"

GET/v1/emails/received/{id}/attachments/{attachmentId}

Download an attachment

Binary. The response `Content-Type` is the attachment's own MIME type.

Auth: apiKey or jwt

Parameters

Name	In	Required	Description
id	path	required
attachmentId	path	required

Responses

200 : Default Response

curl

curl https://api.zsender.io/v1/emails/received/{id}/attachments/{attachmentId} \
  -H "Authorization: Bearer $ZSENDER_API_KEY"

GET/v1/emails/received/{id}/raw

Fetch the raw MIME message

message/rfc822. The mail server's stored copy, not the sender's original bytes: the mail server prepends four X-Postal-* headers on receipt.

Auth: apiKey or jwt

Parameters

Name	In	Required	Description
id	path	required

Responses

200 : Default Response

curl

curl https://api.zsender.io/v1/emails/received/{id}/raw \
  -H "Authorization: Bearer $ZSENDER_API_KEY"

POST/v1/emails/send

Send an email

`to` accepts up to 50 recipients. `from` accepts a bare address (`hello@yourverifieddomain.com`) or a display name followed by one in angle brackets (`Acme <hello@yourverifieddomain.com>`), on a domain whose sending capability is VERIFIED and enabled. Pass an `Idempotency-Key` header to make the call safe to retry.

Auth: apiKey or jwt

Parameters

Name	In	Required	Description
idempotency-key	header	optional

Request body

Field	Type	Required
attachments	array	optional
attachments[].content_type	string	required
attachments[].data	string	required
attachments[].name	string	required
bcc	array	optional
bcc[]	string	optional
cc	array	optional
cc[]	string	optional
from	string	required
headers	object	optional
html	string	optional
in_reply_to	string	optional
references(1)	array	optional
references(1)[]	string	optional
references(2)	string	optional
reply_to	string	optional
subject	string	required
tag	string	optional
text	string	optional
to	array	required
to[]	string	optional
transactional	boolean	optional

Example request body

{
  "from": "receipts@yourverifieddomain.com",
  "html": "<p>Hi Jane, thanks for your payment, your receipt for September is attached below.</p>",
  "subject": "Your zSender receipt for September",
  "tag": "receipt-monthly",
  "to": [
    "jane.doe@example.com"
  ],
  "transactional": true
}

Responses

200 : Default Response

Field	Type	Required
message_id	string	required · nullable
messages	object	required
suppressed	array	required
suppressed[].email	string	required
suppressed[].reason	string	required

curl

curl https://api.zsender.io/v1/emails/send \
  -X POST \
  -H "Authorization: Bearer $ZSENDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "from": "receipts@yourverifieddomain.com",
  "html": "<p>Hi Jane, thanks for your payment, your receipt for September is attached below.</p>",
  "subject": "Your zSender receipt for September",
  "tag": "receipt-monthly",
  "to": [
    "jane.doe@example.com"
  ],
  "transactional": true
}'