Email marketing API: send email, manage contacts and get webhooks
Hemero has a REST API for sending email and managing contacts from your own code, and signed webhooks that tell your server when someone subscribes, unsubscribes, bounces, opens or clicks.
Availability
The REST API and webhooks are live today on every account. Create a key in Settings, API tab.
What the Hemero REST API can do
Every endpoint lives under https://hemero.app/v1 and answers JSON. Errors always look like an error object with a code and a message. The full description is an OpenAPI file at https://hemero.app/openapi.json.
Send email
POST /v1/emails sends one email, POST /v1/emails/batch sends up to 100, and GET /v1/emails/{id} returns the delivery status of an email you sent through the API.
Contacts
POST /v1/contacts creates or updates a contact with name, lists, tags, attributes and time zone. GET /v1/contacts/{email} reads one, GET /v1/contacts lists them newest first with filters for status and source, and POST /v1/contacts/{email}/unsubscribe unsubscribes and suppresses an address.
Lists and forms
GET /v1/lists and GET /v1/forms return the IDs and names you need to add contacts to a list or to subscribe a webhook to a form.
Webhooks
GET, POST and DELETE on /v1/webhooks manage the endpoints that receive events, so a tool or a deploy script can register itself.
API keys and access
Owners and admins create keys in Settings, API tab. Send the key as a bearer token: Authorization: Bearer mt_… A key is shown once when it is created, Hemero stores only a hash, and you can revoke it at any time. Each key has a scope: send only, which allows sending email, or full access, which also allows contacts, lists, forms and webhooks. Requests are limited to 600 a minute per key.
Send an email with curl
The sender must be an address on a domain you have verified in Hemero. The body needs html, text or both. The Idempotency-Key header is optional: sending the same key again returns the original result instead of sending a second email.
curl -X POST https://hemero.app/v1/emails \
-H "Authorization: Bearer mt_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1234" \
-d '{"to":"[email protected]","from":"[email protected]",
"subject":"Your order shipped","html":"<p>On its way!</p>"}'
A new email answers 201 with its id and status. Each email costs one email from your balance. Recipients on your suppression list are refused, and so is a sender from an unverified domain.
Webhooks for email events
Add an endpoint in Settings, Webhooks tab, or with POST /v1/webhooks, and choose the events you want. The URL must be https. Hemero sends a POST with a JSON body of the event name, the time and the data.
Contact events
contact.subscribed, contact.unsubscribed, contact.bounced, contact.complained and form.submitted. A form submission is reported after it is confirmed, so with double opt-in it arrives when the person confirms.
Email, campaign and automation events
email.delivered, email.opened, email.clicked, email.bounced and email.complained, plus campaign.sent, campaign.paused and automation.paused, for example when Hemero pauses a send to protect your reputation.
Signature
Each delivery carries an X-Hemero-Signature header with a timestamp and an HMAC-SHA256 of the timestamp, a dot and the raw body, made with your endpoint's secret. Recompute it on your server and compare. The secret is shown once, and you can rotate it from Settings.
Retries
A delivery has 10 seconds to answer with a success code. Failed ones are retried with a growing delay, up to six attempts. An endpoint that fails 20 times in a row is switched off, and you can switch it back on. You can have up to 20 endpoints, and the Webhooks tab lists recent deliveries and can send a test.
Use Hemero from an AI assistant
Hemero also offers an MCP connector, so Claude, ChatGPT or Cursor can work in your account. Setup is one click and a browser sign-in: see AI agents (MCP). The assistant acts with your role, can be limited to read only, and each connection can be revoked.
What the API does not do
The REST API does not create or send campaigns, edit templates or segments, create forms, import contacts in bulk or delete contacts: you work with contacts one at a time, and unsubscribing is the closest thing to removing one. Campaigns and automations are built in the Hemero app. The API does not bypass the safeguards: unverified domains, suppressed addresses and sending limits apply to it too. Emails sent through it use your email balance like any other: see pricing.
Questions
Does Hemero have an email marketing API?
Yes. The REST API sends email and manages contacts, lists and webhooks, and it is described in an OpenAPI file at hemero.app/openapi.json. Campaigns themselves are built in the app.
How do I authenticate to the Hemero API?
Create an API key in Settings, API tab, and send it as Authorization: Bearer followed by the key. Use a send-only key for code that only sends email.
How do I verify a Hemero webhook?
Read the X-Hemero-Signature header, which holds a timestamp and a signature. Compute an HMAC-SHA256 of the timestamp, a dot and the raw request body with your endpoint's secret, and compare it to the signature.
What happens if my webhook endpoint is down?
Hemero retries the delivery with a growing delay, up to six attempts. After 20 failures in a row the endpoint is switched off until you turn it back on.
Build on an email platform with the safeguards included. Create your account, make a key and send your first email from code.