REST API

Mail API

REST endpoints for the Mail area of Lessly.

The Mail area publishes 51 REST endpoints. Paths are relative to https://api.lessly.com; see Authentication for the required header.

GET/mail/api-keys

List active API keys (prefix + metadata only, never the secret)

MCP tool: mail_apikey_list

Parameters

No parameters.

POST/mail/api-keys

Issue a scoped sending API key; the full secret is returned only once

MCP tool: mail_apikey_create

Parameters

Name	In	Type	Required	Description
name	body	string	•	Human-readable label for the key
scope	body	string	•	Permission scope: 'full_access' or 'sending_access'
domainId	body	string	—	Optional Domain id this key is locked to

Response

Field	Type	Always	Description
id	string	•	—
key	string	•	—
name	string	•	—
scope	string	•	—
prefix	string	•	—
domainId	string	•	—
createdAt	string	•	—

DELETE/mail/api-keys/:id

Revoke an API key by id

MCP tool: mail_apikey_delete

Parameters

Name	In	Type	Required	Description
id	path	string	•	UUID of the API key to revoke

Response

Field	Type	Always	Description
id	string	•	—
revoked	boolean	•	—

GET/mail/audiences

List audiences for the current product

MCP tool: mail_audience_list

Parameters

No parameters.

POST/mail/audiences

Create an audience (a named bucket of contacts) for the current product

MCP tool: mail_audience_create

Parameters

Name	In	Type	Required	Description
name	body	string	•	Human label for the audience

Response

Field	Type	Always	Description
id	string	•	—
name	string	•	—
createdAt	string	•	—
updatedAt	string	•	—

GET/mail/audiences/:audienceId/contacts

List contacts in an audience

MCP tool: mail_contact_list

Parameters

Name	In	Type	Required	Description
audience_id	query	string	•	Audience to list contacts from
unsubscribed	query	string	—	Filter by unsubscribed flag
cursor	query	string	—	Opaque pagination cursor from a prior page
limit	query	integer	—	Max items per page (1–100, default 50)
audienceId	path	string	—	—

Response

Field	Type	Always	Description
data	array	•	—
nextCursor	string	•	—

POST/mail/audiences/:audienceId/contacts

Add a contact to an audience

MCP tool: mail_contact_create

Parameters

Name	In	Type	Required	Description
audience_id	body	string	•	Audience the contact belongs to
email	body	string	•	Contact email address
properties	body	object	—	Custom key/value properties (e.g. first_name, last_name)
unsubscribed	body	boolean	—	Marketing opt-out flag
audienceId	path	string	—	—

Response

Field	Type	Always	Description
id	string	•	—
email	string	•	—
createdAt	string	•	—
updatedAt	string	•	—
audienceId	string	•	—
properties	string	—	—
unsubscribed	boolean	•	—

DELETE/mail/audiences/:audienceId/contacts/:id

Delete a contact from an audience

MCP tool: mail_contact_delete

Parameters

Name	In	Type	Required	Description
audience_id	body	string	•	Audience id
id	path	string	•	Contact id
audienceId	path	string	—	—

Response

Field	Type	Always	Description
deleted	boolean	•	—

GET/mail/audiences/:audienceId/contacts/:id

Get a single contact by id

MCP tool: mail_contact_get

Parameters

Name	In	Type	Required	Description
audience_id	body	string	•	Audience id
id	path	string	•	Contact id
audienceId	path	string	—	—

Response

Field	Type	Always	Description
id	string	•	—
email	string	•	—
createdAt	string	•	—
updatedAt	string	•	—
audienceId	string	•	—
properties	string	—	—
unsubscribed	boolean	•	—

PATCH/mail/audiences/:audienceId/contacts/:id

Update a contact (properties or unsubscribed flag)

MCP tool: mail_contact_update

Parameters

Name	In	Type	Required	Description
audience_id	body	string	•	Audience id
id	path	string	•	Contact id
properties	body	object	—	Replace the custom properties object
unsubscribed	body	boolean	—	Set the marketing opt-out flag
audienceId	path	string	—	—

Response

Field	Type	Always	Description
id	string	•	—
email	string	•	—
createdAt	string	•	—
updatedAt	string	•	—
audienceId	string	•	—
properties	string	—	—
unsubscribed	boolean	•	—

DELETE/mail/audiences/:id

Delete an audience and all its contacts (cascade)

MCP tool: mail_audience_delete

Parameters

Name	In	Type	Required	Description
id	path	string	•	Audience id to delete

Response

Field	Type	Always	Description
deleted	boolean	•	—

GET/mail/audiences/:id

Get a single audience by id

MCP tool: mail_audience_get

Parameters

Name	In	Type	Required	Description
id	path	string	•	Audience id

Response

Field	Type	Always	Description
id	string	•	—
name	string	•	—
createdAt	string	•	—
updatedAt	string	•	—

PATCH/mail/audiences/:id

Rename an audience

MCP tool: mail_audience_update

Parameters

Name	In	Type	Required	Description
id	path	string	•	Audience id
name	body	string	—	New name

Response

Field	Type	Always	Description
id	string	•	—
name	string	•	—
createdAt	string	•	—
updatedAt	string	•	—

GET/mail/broadcasts

List broadcasts for the product (cursor-paginated)

MCP tool: mail_broadcast_list

Parameters

Name	In	Type	Required	Description
cursor	query	string	—	—
limit	query	integer	—	—

Response

Field	Type	Always	Description
items	array	•	—
nextCursor	string	•	—

POST/mail/broadcasts

Create a draft broadcast (inline content or a template reference) targeting an audience

MCP tool: mail_broadcast_create

Parameters

Name	In	Type	Required	Description
name	body	string	•	—
audienceId	body	string	•	—
from	body	string	•	—
replyTo	body	array	—	—
headers	body	object	—	—
subject	body	string	—	—
html	body	string	—	—
text	body	string	—	—
template	body	object	—	—

Response

Field	Type	Always	Description
id	string	•	—
from	string	•	—
html	string	•	—
name	string	•	—
text	string	•	—
sentAt	string	•	—
status	string	•	—
headers	object	•	—
replyTo	array	•	—
subject	string	•	—
queuedAt	string	•	—
createdAt	string	•	—
lastError	string	•	—
productId	string	•	—
updatedAt	string	•	—
variables	string	—	—
audienceId	string	•	—
templateId	string	•	—
recipientCount	number	•	—

DELETE/mail/broadcasts/:id

Delete a draft broadcast

MCP tool: mail_broadcast_delete

Parameters

Name	In	Type	Required	Description
id	path	string	•	—

Response

Field	Type	Always	Description
id	string	•	—
deleted	boolean	•	—

GET/mail/broadcasts/:id

Get one broadcast by id

MCP tool: mail_broadcast_get

Parameters

Name	In	Type	Required	Description
id	path	string	•	—

Response

Field	Type	Always	Description
id	string	•	—
from	string	•	—
html	string	•	—
name	string	•	—
text	string	•	—
sentAt	string	•	—
status	string	•	—
headers	object	•	—
replyTo	array	•	—
subject	string	•	—
queuedAt	string	•	—
createdAt	string	•	—
lastError	string	•	—
productId	string	•	—
updatedAt	string	•	—
variables	string	—	—
audienceId	string	•	—
templateId	string	•	—
recipientCount	number	•	—

PATCH/mail/broadcasts/:id

Edit a draft broadcast

MCP tool: mail_broadcast_update

Parameters

Name	In	Type	Required	Description
name	body	string	—	—
audienceId	body	string	—	—
from	body	string	—	—
replyTo	body	array	—	—
headers	body	object	—	—
subject	body	string	—	—
html	body	string	—	—
text	body	string	—	—
template	body	object	—	—
id	path	string	•	—

Response

Field	Type	Always	Description
id	string	•	—
from	string	•	—
html	string	•	—
name	string	•	—
text	string	•	—
sentAt	string	•	—
status	string	•	—
headers	object	•	—
replyTo	array	•	—
subject	string	•	—
queuedAt	string	•	—
createdAt	string	•	—
lastError	string	•	—
productId	string	•	—
updatedAt	string	•	—
variables	string	—	—
audienceId	string	•	—
templateId	string	•	—
recipientCount	number	•	—

POST/mail/broadcasts/:id/cancel

Cancel a draft or queued broadcast

MCP tool: mail_broadcast_cancel

Parameters

Name	In	Type	Required	Description
id	path	string	•	—

Response

Field	Type	Always	Description
id	string	•	—
from	string	•	—
html	string	•	—
name	string	•	—
text	string	•	—
sentAt	string	•	—
status	string	•	—
headers	object	•	—
replyTo	array	•	—
subject	string	•	—
queuedAt	string	•	—
createdAt	string	•	—
lastError	string	•	—
productId	string	•	—
updatedAt	string	•	—
variables	string	—	—
audienceId	string	•	—
templateId	string	•	—
recipientCount	number	•	—

POST/mail/broadcasts/:id/queue

Queue a draft broadcast — fans out one email per eligible contact

MCP tool: mail_broadcast_queue

Parameters

Name	In	Type	Required	Description
id	path	string	•	—

Response

Field	Type	Always	Description
id	string	•	—
from	string	•	—
html	string	•	—
name	string	•	—
text	string	•	—
sentAt	string	•	—
status	string	•	—
headers	object	•	—
replyTo	array	•	—
subject	string	•	—
queuedAt	string	•	—
createdAt	string	•	—
lastError	string	•	—
productId	string	•	—
updatedAt	string	•	—
variables	string	—	—
audienceId	string	•	—
templateId	string	•	—
recipientCount	number	•	—

GET/mail/broadcasts/:id/stats

Per-broadcast analytics: recipients/suppressed/failed + delivered/opened/clicked/bounced

MCP tool: mail_broadcast_stats

Parameters

Name	In	Type	Required	Description
id	path	string	•	—

Response

Field	Type	Always	Description
failed	number	•	—
opened	number	•	—
bounced	number	•	—
clicked	number	•	—
delivered	number	•	—
recipients	number	•	—
suppressed	number	•	—

GET/mail/domains

List sending domains for the current product

MCP tool: mail_domain_list

Parameters

No parameters.

POST/mail/domains

MCP tool: mail_domain_create

Parameters

Name	In	Type	Required	Description
name	body	string	•	The sending domain to register, e.g. "example.com"
region	body	string	—	AWS region for the SES identity (data residency); immutable after create

Response

Field	Type	Always	Description
id	string	•	—
tls	string	•	—
apex	string	•	—
mode	string	•	—
name	string	•	—
active	boolean	•	—
region	string	•	—
status	string	•	—
records	array	•	—
createdAt	string	•	—
updatedAt	string	•	—
verifiedAt	string	•	—
instructions	array	•	—
openTracking	boolean	•	—
bindingStatus	string	•	—
clickTracking	boolean	•	—
customReturnPath	string	•	—
trackingSubdomain	string	•	—
governanceDomainId	string	•	—
governanceBindingId	string	•	—
verificationStartedAt	string	•	—
lastVerificationCheckAt	string	•	—

DELETE/mail/domains/:id

Delete a sending domain and its SES identity

MCP tool: mail_domain_delete

Parameters

Name	In	Type	Required	Description
id	path	string	•	Domain id to delete

Response

Field	Type	Always	Description
deleted	boolean	•	—

GET/mail/domains/:id

Get a sending domain with its DNS records and per-record verification status

MCP tool: mail_domain_get

Parameters

Name	In	Type	Required	Description
id	path	string	•	Domain id

Response

Field	Type	Always	Description
id	string	•	—
tls	string	•	—
apex	string	•	—
mode	string	•	—
name	string	•	—
active	boolean	•	—
region	string	•	—
status	string	•	—
records	array	•	—
createdAt	string	•	—
updatedAt	string	•	—
verifiedAt	string	•	—
instructions	array	•	—
openTracking	boolean	•	—
bindingStatus	string	•	—
clickTracking	boolean	•	—
customReturnPath	string	•	—
trackingSubdomain	string	•	—
governanceDomainId	string	•	—
governanceBindingId	string	•	—
verificationStartedAt	string	•	—
lastVerificationCheckAt	string	•	—

PATCH/mail/domains/:id

Update tracking / TLS / return-path config for a domain

MCP tool: mail_domain_update

Parameters

Name	In	Type	Required	Description
id	path	string	•	Domain id
openTracking	body	boolean	—	Enable open tracking (1×1 pixel); off by default
clickTracking	body	boolean	—	Enable click tracking (link rewrite); off by default
trackingSubdomain	body	string	—	Host used for the click-redirect and open-pixel
tls	body	string	—	TLS policy: opportunistic (default) or enforced

Response

Field	Type	Always	Description
id	string	•	—
tls	string	•	—
apex	string	•	—
mode	string	•	—
name	string	•	—
active	boolean	•	—
region	string	•	—
status	string	•	—
records	array	•	—
createdAt	string	•	—
updatedAt	string	•	—
verifiedAt	string	•	—
instructions	array	•	—
openTracking	boolean	•	—
bindingStatus	string	•	—
clickTracking	boolean	•	—
customReturnPath	string	•	—
trackingSubdomain	string	•	—
governanceDomainId	string	•	—
governanceBindingId	string	•	—
verificationStartedAt	string	•	—
lastVerificationCheckAt	string	•	—

POST/mail/domains/:id/verify

Re-check a domain's DNS + SES verification immediately

MCP tool: mail_domain_verify

Parameters

Name	In	Type	Required	Description
id	path	string	•	Domain id to re-check now

Response

Field	Type	Always	Description
id	string	•	—
tls	string	•	—
apex	string	•	—
mode	string	•	—
name	string	•	—
active	boolean	•	—
region	string	•	—
status	string	•	—
records	array	•	—
createdAt	string	•	—
updatedAt	string	•	—
verifiedAt	string	•	—
instructions	array	•	—
openTracking	boolean	•	—
bindingStatus	string	•	—
clickTracking	boolean	•	—
customReturnPath	string	•	—
trackingSubdomain	string	•	—
governanceDomainId	string	•	—
governanceBindingId	string	•	—
verificationStartedAt	string	•	—
lastVerificationCheckAt	string	•	—

GET/mail/domains/allowed

List apex domains this product may register sending domains under (from governance)

MCP tool: mail_domain_allowed_list

Parameters

No parameters.

POST/mail/emails

Send a single email

MCP tool: mail_email_send

Parameters

Name	In	Type	Required	Description
from	body	string	•	Sender, e.g. "Name <you@your-domain.com>"
to	body	string	—	Primary recipient(s)
cc	body	string	—	Cc recipient(s)
bcc	body	string	—	Bcc recipient(s) — not shown in headers
subject	body	string	—	Email subject (required for inline sends)
reply_to	body	string	—	Reply-To address(es)
html	body	string	—	HTML body
text	body	string	—	Plain-text body; auto-derived from html if omitted
headers	body	object	—	Custom headers map
tags	body	array	—	Metadata tags
template	body	object	—	Send by reference to a published template
scheduled_at	body	string	—	ISO-8601 instant to send at; future, within 30 days. Omit to send now.

Response

Field	Type	Always	Description
id	string	•	—

GET/mail/emails/:id

Retrieve an email by id, with its last event

MCP tool: mail_email_get

Parameters

Name	In	Type	Required	Description
id	path	string	•	Email id

PATCH/mail/emails/:id

Reschedule a scheduled email to a new ISO-8601 instant

MCP tool: mail_email_update

Parameters

Name	In	Type	Required	Description
scheduled_at	body	string	•	New ISO-8601 instant; future, within 30 days
id	path	string	•	Email id

Response

Field	Type	Always	Description
id	string	•	—

POST/mail/emails/:id/cancel

Cancel a scheduled email

MCP tool: mail_email_cancel

Parameters

Name	In	Type	Required	Description
id	path	string	•	Email id

Response

Field	Type	Always	Description
id	string	•	—
status	string	•	—

POST/mail/emails/batch

Send up to 100 emails in one atomic batch

MCP tool: mail_email_send_batch

Parameters

Name	In	Type	Required	Description
emails	body	array	•	Up to 100 emails to send, each shaped like a single send

GET/mail/reputation

Current sender-reputation status for the product: hard-bounce and complaint rates over the rolling window, the sample volume, whether sends are throttled, the tripped metric, and the configured thresholds

MCP tool: mail_reputation_get

Parameters

No parameters.

Response

Field	Type	Always	Description
gated	boolean	•	—
volume	number	•	—
complaints	number	•	—
thresholds	object	•	—
window_days	number	•	—
hard_bounces	number	•	—
complaint_rate	number	•	—
tripped_metric	string	•	—
hard_bounce_rate	number	•	—

GET/mail/stats

Dashboard aggregation for the product over 7d|30d|90d: sent/delivered/bounced/complained totals, period-over-period deltas, daily volume buckets, and deliverability percentages

MCP tool: mail_stats_get

Parameters

Name	In	Type	Required	Description
period	query	string	—	—

Response

Field	Type	Always	Description
range	object	•	—
deltas	object	•	—
period	string	•	—
totals	object	•	—
volume	array	•	—
deliverability	object	•	—

GET/mail/suppressions

List suppressed recipient addresses for the current product (paginated, filter by reason or address substring)

MCP tool: mail_suppression_list

Parameters

Name	In	Type	Required	Description
reason	query	string	—	Filter by reason
q	query	string	—	Case-insensitive substring match on address
cursor	query	string	—	Opaque pagination cursor from a prior page
limit	query	integer	—	Max items per page (1–100, default 50)

Response

Field	Type	Always	Description
items	array	•	—
next_cursor	string	•	—

POST/mail/suppressions

Manually suppress a recipient address (reason is always "manual"); idempotent

MCP tool: mail_suppression_add

Parameters

Name	In	Type	Required	Description
address	body	string	•	Email address to suppress
note	body	string	—	Optional free-text note

Response

Field	Type	Always	Description
id	string	•	—
note	string	•	—
reason	string	•	—
address	string	•	—
created_at	string	•	—
source_event_id	string	•	—

DELETE/mail/suppressions/:address

Remove an address from the suppression list; idempotent (returns whether a row existed)

MCP tool: mail_suppression_remove

Parameters

Name	In	Type	Required	Description
address	path	string	•	Email address to remove from the suppression list

Response

Field	Type	Always	Description
address	string	•	—
removed	boolean	•	—

GET/mail/templates

List email templates for the current product

MCP tool: mail_template_list

Parameters

No parameters.

POST/mail/templates

Create a draft email template with typed {{ variable }} placeholders

MCP tool: mail_template_create

Parameters

Name	In	Type	Required	Description
name	body	string	•	Human label for the template
subject	body	string	•	Email subject; may contain {{ variable }} placeholders
html	body	string	•	HTML body; may contain {{ variable }} placeholders
text	body	string	—	Optional plaintext body; derived from html when omitted
variables	body	array	—	Declared variables ([{name,type,optional,fallback}], <=20)

Response

Field	Type	Always	Description
id	string	•	—
html	string	•	—
name	string	•	—
text	string	•	—
status	string	•	—
subject	string	•	—
createdAt	string	•	—
updatedAt	string	•	—
variables	array	•	—

DELETE/mail/templates/:id

Delete a template

MCP tool: mail_template_delete

Parameters

Name	In	Type	Required	Description
id	path	string	•	Template id to delete

Response

Field	Type	Always	Description
deleted	boolean	•	—

GET/mail/templates/:id

Get a single email template by id

MCP tool: mail_template_get

Parameters

Name	In	Type	Required	Description
id	path	string	•	Template id

Response

Field	Type	Always	Description
id	string	•	—
html	string	•	—
name	string	•	—
text	string	•	—
status	string	•	—
subject	string	•	—
createdAt	string	•	—
updatedAt	string	•	—
variables	array	•	—

PATCH/mail/templates/:id

Update a draft template (published templates are not editable)

MCP tool: mail_template_update

Parameters

Name	In	Type	Required	Description
id	path	string	•	Template id
name	body	string	—	—
subject	body	string	—	—
html	body	string	—	—
text	body	string	—	—
variables	body	array	—	—

Response

Field	Type	Always	Description
id	string	•	—
html	string	•	—
name	string	•	—
text	string	•	—
status	string	•	—
subject	string	•	—
createdAt	string	•	—
updatedAt	string	•	—
variables	array	•	—

POST/mail/templates/:id/publish

Publish a template (draft -> published)

MCP tool: mail_template_publish

Parameters

Name	In	Type	Required	Description
id	path	string	•	Template id to publish

Response

Field	Type	Always	Description
id	string	•	—
html	string	•	—
name	string	•	—
text	string	•	—
status	string	•	—
subject	string	•	—
createdAt	string	•	—
updatedAt	string	•	—
variables	array	•	—

GET/mail/usage

Current free-tier usage for the product: emails sent this day and month with used/limit/remaining, the hard cap, a blocked flag, and the point-in-time contacts count

MCP tool: mail_usage_get

Parameters

No parameters.

Response

Field	Type	Always	Description
emails	object	•	—
period	object	•	—
contacts	object	•	—

GET/mail/webhooks

List webhook endpoints for the current product (secret omitted).

MCP tool: mail_webhook_list

Parameters

No parameters.

POST/mail/webhooks

MCP tool: mail_webhook_create

Parameters

Name	In	Type	Required	Description
url	body	string	•	HTTPS URL that signed events are POSTed to
enabled_events	body	array	•	Event types to deliver. One or more of: email.delivered, email.bounced, email.complained, email.suppressed, email.opened, email.clicked
description	body	string	—	Optional human label

Response

Field	Type	Always	Description
id	string	•	—
url	string	•	—
secret	string	•	—
enabled	boolean	•	—
created_at	string	•	—
updated_at	string	•	—
description	string	•	—
enabled_events	array	•	—

DELETE/mail/webhooks/:id

Delete a webhook endpoint.

MCP tool: mail_webhook_delete

Parameters

Name	In	Type	Required	Description
id	path	string	•	Webhook endpoint id

Response

Field	Type	Always	Description
id	string	•	—
deleted	boolean	•	—

GET/mail/webhooks/:id

Get a webhook endpoint by id (secret omitted).

MCP tool: mail_webhook_get

Parameters

Name	In	Type	Required	Description
id	path	string	•	Webhook endpoint id

Response

Field	Type	Always	Description
id	string	•	—
url	string	•	—
enabled	boolean	•	—
created_at	string	•	—
updated_at	string	•	—
description	string	•	—
enabled_events	array	•	—

PATCH/mail/webhooks/:id

Update a webhook endpoint (url, enabled_events, description, or enable/disable).

MCP tool: mail_webhook_update

Parameters

Name	In	Type	Required	Description
id	path	string	•	Webhook endpoint id
url	body	string	—	HTTPS URL that signed events are POSTed to
enabled_events	body	array	—	Event types to deliver. One or more of: email.delivered, email.bounced, email.complained, email.suppressed, email.opened, email.clicked
description	body	string	—	Optional human label
enabled	body	boolean	—	Enable (true) or disable (false) delivery

Response

Field	Type	Always	Description
id	string	•	—
url	string	•	—
enabled	boolean	•	—
created_at	string	•	—
updated_at	string	•	—
description	string	•	—
enabled_events	array	•	—

GET/mail/webhooks/:id/deliveries

List recent delivery attempts for a webhook endpoint (status, attempts, last error).

MCP tool: mail_webhook_deliveries_list

Parameters

Name	In	Type	Required	Description
id	path	string	•	Webhook endpoint id
limit	query	integer	—	Max items (1-100, default 50)

Was this page helpful?