Developers · API

Hyo Mail REST API

Send transactional email, read delivery events, and keep contacts and orders in sync from your own systems at api.hyonova.com.

  • Base URL https://api.hyonova.com
  • Bearer API keys with scopes
  • 600 requests per minute per key
A server and a laptop exchanging requests, secured with an API key.

At a glance

What is it?

The public REST API of Hyo Mail. Your servers send transactional email, read the message log and sync contacts and conversions with JSON over HTTPS.

Who is it for?

Developers who send receipts, confirmations and account notices from their own product, and teams that sync contacts from another system.

How is it priced?

The API is included in every plan. Each message uses one Mail credit; your plan sets no monthly allowance and no daily cap.

Endpoints

Send an email

POST /mail/v1/send queues one message from a template with variables, or from a subject and HTML, and returns 202 with the message id.

Message log

GET /mail/v1/messages lists messages newest first, filtered by status, recipient, tag or date, with cursor pagination.

One message

GET /mail/v1/messages/{id} returns a message with its delivery events.

Contacts

GET and POST /mail/v1/contacts list contacts and create or update one by email, with its consent.

Conversions

POST /mail/v1/conversions records an order or another conversion for campaign attribution.

Forms

GET /mail/v1/forms lists your active sign-up forms.

Key check

GET /mail/v1/me returns the company, the key's scopes and your limits.

OpenAPI

GET /mail/v1/openapi.json returns the OpenAPI 3.0 document, without a key.

Send your first email

Verify a sender

Verify your domain (DKIM, SPF and DMARC) and add a sender in Hyo Mail. Without one, sending answers 409 SENDER_NOT_VERIFIED.

Create a key

In Mail › Automations › API keys, select mail.transactional.send and copy the key. It starts with hnm_ and is shown once.

Call the API

POST to https://api.hyonova.com/mail/v1/send with Authorization: Bearer and your key, the recipient and a template or HTML.

Make retries safe

Send an Idempotency-Key. Repeating the same call returns the first result instead of sending twice.

Built for production

Clear errors

JSON errors with a code and a request id, and standard HTTP statuses such as 402 INSUFFICIENT_CREDITS.

Rate-limit headers

Every response carries x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset.

Fair credits

A message that the email service permanently rejects gets its credit back.

Questions and answers

Which scopes exist?

mail.transactional.send, mail.events.read, mail.contacts.read, mail.contacts.write, mail.conversions.write, and mail.integrations.write for the WordPress plugin.

What happens when credits run out?

Sending answers 402 INSUFFICIENT_CREDITS and nothing is queued. Add credits and send again with a new idempotency key.

Can I send my own HTML?

Yes. Send subject and html instead of templateId. Unsafe content is removed.

How do I know a message was delivered?

Read it with GET /mail/v1/messages/{id}, or subscribe to the delivered and bounced webhooks.

Send email from your product

Start free, verify your domain and create your first API key.