Mail API

The Hyo Mail API lets your own product send transactional email — receipts, confirmations, account notices — one message per call, read each message's status, and keep your contacts in sync. It is part of Hyo Mail, and every plan includes it.

Base URL and authentication#

All endpoints live under one base URL:

https://api.hyonova.com

Send an API key as a bearer token on every call:

Authorization: Bearer YOUR_API_KEY

Keys start with hnm_. Keep them on your servers. Never put an API key in a web page or a mobile app.

Mail › Automations › API guide shows the same address as Endpoint, with a copy button.

Before you start#

• A verified sender. Your company verifies its own sending domain (DKIM, SPF through a custom MAIL FROM domain, and DMARC) and adds a sender address on it. Without one, sending answers 409 SENDER_NOT_VERIFIED. See Senders, domains and settings.
• Mail credits. Each message uses one Mail credit. See Credits below.
• An API key. Someone with Mail administration — by default an Owner or Admin — creates it.

API keys#

The table of keys shows each key's prefix, scopes and Last used. Revoke stops a key immediately; calls with it then answer 401 API_KEY_INVALID. HyoNova stores only a hash of each key.

Endpoints#

To be told about delivery events instead of asking, use Webhooks.

Send an email#

POST /mail/v1/send queues one message and answers 202 Accepted. Send either a template with variables, or a subject and HTML:

Templates use variables such as {{ order_number }}, with an optional fallback: {{ order_number | default:"—" }}. Values are always inserted as text.

curl -X POST "https://api.hyonova.com/mail/v1/send" \
  -H "Authorization: Bearer $HYO_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1001-confirmation" \
  -d '{
    "to": { "email": "name@example.com", "name": "Customer" },
    "templateId": "TEMPLATE_ID",
    "variables": { "order_number": "1001" }
  }'

const response = await fetch('https://api.hyonova.com/mail/v1/send', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.HYO_MAIL_API_KEY}`, // YOUR_API_KEY
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-1001-confirmation',
  },
  body: JSON.stringify({
    to: { email: 'name@example.com', name: 'Customer' },
    templateId: 'TEMPLATE_ID',
    variables: { order_number: '1001' },
  }),
});

const result = await response.json();
if (response.status !== 202) {
  throw new Error(`${result.error.code}: ${result.error.message}`);
}
console.log(result.id, result.status); // status is "queued"

<?php
$payload = json_encode([
    'to' => ['email' => 'name@example.com', 'name' => 'Customer'],
    'templateId' => 'TEMPLATE_ID',
    'variables' => ['order_number' => '1001'],
]);

$ch = curl_init('https://api.hyonova.com/mail/v1/send');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('HYO_MAIL_API_KEY'), // YOUR_API_KEY
        'Content-Type: application/json',
        'Idempotency-Key: order-1001-confirmation',
    ],
    CURLOPT_POSTFIELDS => $payload,
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$result = json_decode((string) $body, true);
if ($status !== 202) {
    throw new RuntimeException($result['error']['code'] . ': ' . $result['error']['message']);
}
echo $result['id'];

The response:

{ "id": "6f1c2d4e-9a7b-4c1d-8e2f-3a4b5c6d7e8f", "status": "queued", "replayed": false }

Keep the id: it identifies the message in the message log, in GET /mail/v1/messages/{id} and in webhook events.

Idempotency#

Give every logical message its own key — for example order-1001-confirmation — and send the same key again when you retry after a timeout or a network error.

• The Idempotency-Key header works on every POST endpoint. The first answer under a key is kept for 24 hours for that API key. A retry with the same key and the same body gets the same answer again, with the header Idempotent-Replayed: true. The same key with a different body answers 409 IDEMPOTENCY_CONFLICT. Header keys can be up to 200 characters.
• On POST /mail/v1/send the key also names the message for your whole company: a later call with the same key returns the original message with "replayed": true and sends nothing new. Keep send keys to 160 characters.

Read a message#

GET /mail/v1/messages/{id} returns one message with its events:

curl "https://api.hyonova.com/mail/v1/messages/MESSAGE_ID" \
  -H "Authorization: Bearer $HYO_MAIL_API_KEY"

{
  "id": "6f1c2d4e-9a7b-4c1d-8e2f-3a4b5c6d7e8f",
  "recipient": "name@example.com",
  "subject": "Your order 1001",
  "templateId": "TEMPLATE_ID",
  "status": "delivered",
  "providerMessageId": "…",
  "errorCode": null,
  "createdAt": "2026-10-18T09:30:00.000Z",
  "sentAt": "2026-10-18T09:30:02.000Z",
  "lastEventAt": "2026-10-18T09:30:05.000Z",
  "events": [
    { "type": "sent", "at": "2026-10-18T09:30:02.000Z" },
    { "type": "delivery", "at": "2026-10-18T09:30:05.000Z" }
  ]
}

GET /mail/v1/messages lists messages, newest first, as { "items": [...], "nextCursor": "…" }. Query parameters: limit (1–100, default 25), cursor (the previous nextCursor), status, q (part of the recipient or subject), since (an ISO date-time) and tag (a tag key).

Message statuses#

An unsubscribe from marketing email does not stop transactional email. A hard bounce or a complaint does.

Account: GET /mail/v1/me#

Use it to check a key. It returns the organization (id, name), the key (id, name, prefix, scopes, expiresAt), entitlements (api, smtp), limits (requestsPerMinute, idempotencyWindowHours, keyRotationGraceHours) and apiVersion.

Contacts#

GET /mail/v1/contacts lists contacts as { "items": [...], "nextCursor": "…" }, with limit, cursor, status, q, tag and listId. GET /mail/v1/contacts/{id} accepts a contact ID or an email address.

POST /mail/v1/contacts creates or updates a contact by email. Fields: email (required), firstName, lastName, company, phone, locale, attributes, tags, listIds (up to 20), status (subscribed, pending or unsubscribed) and consent.

Consent is honest by design:

• A contact becomes subscribed only when you also send consent — { "source": "checkout opt-in", "at": "2026-10-18T09:30:00Z", "reference": "order-1001" }. Without it, a new contact is pending and receives no marketing email.
• The API never overwrites a stronger state: an unsubscribed, suppressed, bounced or complained contact stays that way.

The answer is the contact, plus created (true for a new contact) and marketable (true only for subscribed).

curl -X POST "https://api.hyonova.com/mail/v1/contacts" \
  -H "Authorization: Bearer $HYO_MAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-name@example.com" \
  -d '{
    "email": "name@example.com",
    "firstName": "Sam",
    "status": "subscribed",
    "consent": { "source": "website newsletter form" }
  }'

Forms and conversions#

• GET /mail/v1/forms lists your active sign-up forms with publicId, name, fields, consentText, doubleOptIn, language and the hosted url. The WordPress plugin uses it.
• POST /mail/v1/conversions records an order or another conversion, so campaign reports can attribute revenue to the last verified click. Fields: eventId (your stable ID — sending it again never adds revenue twice), eventType (purchase, order_confirmed, registration, lead or booking), one of contactId, email or customerRef, revenue, currency (three letters, default USD), status (completed, refunded or cancelled), refundedAmount, occurredAt and metadata. It answers 202 with the conversion and an outcome. This endpoint accepts up to 300 requests per minute per key.

Errors#

Errors use this shape. Branch on code, not on the message. Every response carries an X-Request-Id header; include it when you contact HyoNova.

{ "error": { "code": "SENDER_NOT_VERIFIED", "message": "Add and verify a sender before sending." } }

Credits#

Each message uses one Mail credit, charged once, when the message is handed to the email service:

• Retries never charge again.
• A message the email service permanently rejects gets its credit back. A bounce after the message was accepted does not.
• When the wallet is empty, POST /mail/v1/send answers 402 INSUFFICIENT_CREDITS. If credits run out between queueing and sending, the message is marked failed with MAIL_CREDITS_EXHAUSTED. Add credits and send it again with a new idempotency key.

There is no monthly allowance and no plan daily cap. See Mail and Sign capacity.

Limits#

• Requests. 600 requests per minute per API key (300 for POST /mail/v1/conversions). Every answer carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset; a 429 also carries retry-after.
• Delivery pace. HyoNova paces all sending to stay within its email provider's limits, so a message can wait briefly as queued or deferred before it is sent.
• Size. html up to 400,000 characters; subject up to 500.

The message log#

Mail › Automations › Messages lists every message sent through the API, with its Recipient, Status and Last event. Open one to see its Events and the Provider message ID. Anyone with access to Mail can read the log; the API keys and Webhooks tabs are for Mail administrators.

SMTP relay#

Status#