# Mail API

The Mail area publishes 51 REST endpoints. Paths are relative to `https://api.lessly.com`; see [Authentication](/reference/openapi#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`

Register a sending domain (SES Easy DKIM) and return the DNS records to publish

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`

Register a webhook endpoint for the current product. Returns the signing secret ONCE.

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) |