Transactional email API: send email from your own code
One request sends a receipt, a password reset or a notification from your verified domain. Signed webhooks tell your app what happened to each email.
What a transactional email API is
Transactional emails are the one-to-one messages your product sends because of something a person did: an order receipt, a password reset, a shipping update. They are different from campaigns, which you send to a list. Hemero's REST API lets your backend send them through the same verified domains as your campaigns.
How to send your first email through the API
Verify a domain
Add and verify a sending domain under Domains. The API only sends from addresses on a domain you have verified. See deliverability for how.
Create an API key
Open Settings, then API, and click New API key. Choose Send only for transactional email or Full access if you also want to manage contacts. The token is shown once, so store it safely; Hemero only keeps a hash. Owners and admins can create keys.
Send a request
POST to /v1/emails with your key as a Bearer token. The example further down is the real request shape.
Check the result
A new email returns 201 with an id and a status. Use GET /v1/emails/:id to read its status later, or look at Recent API emails in Settings.
Listen for events
Under Settings, then Webhooks, add an endpoint and choose events such as email.delivered, email.opened, email.clicked, email.bounced and email.complained.
Example: send an email with curl
Replace mt_... with your key and use an address on your verified domain in from. The base URL is https://hemero.app/v1. Hemero answers 201 with the email's id when it accepts the message.
curl -X POST https://hemero.app/v1/emails \
-H "Authorization: Bearer mt_..." \
-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>"}'
What the API can do
Send one email
#POST /v1/emailsFields: to, from, subject, and html or text (or both). Optional: replyTo, custom headers and free-form metadata that GET /v1/emails/:id echoes back. From can be an address or Name <address> on a verified domain.
Idempotent retries
#safeAdd an Idempotency-Key header and a retried request returns the original email instead of sending and charging twice.
Send up to 100 at once
#POST /v1/emails/batchSend an array of emails in one request. The response lists which were sent and which failed, with a reason for each.
Signed webhooks
#eventsHemero posts a signed JSON payload to your URL. Verify the X-Hemero-Signature header with your endpoint secret. Failed deliveries retry with backoff, and an endpoint that fails 20 times in a row is disabled.
Contacts and lists
#full accessWith a Full access key you can also create and read contacts, unsubscribe them, list your lists and forms, and manage webhook endpoints.
OpenAPI description
#/openapi.jsonA machine-readable description of the API is published at hemero.app/openapi.json, ready for your code generator or API client.
What it costs
Each recipient of each API email uses one email from your allowance, the same as a campaign recipient, and the email is returned if the send fails. Starter is $19 a month for 25,000 emails, and pay-as-you-go packages never expire; see pricing. The API itself has no extra fee. Every new account starts with 500 free emails once its owner's email is verified.
Honest limits
Suppressed addresses are refused
If the recipient is on your suppression list, the API rejects the email with a suppressed error. That protects your reputation, and it is not something to work around.
Transactional is not marketing
Hemero does not add an unsubscribe link to API emails. Use the API for messages a person expects. For promotions, send a campaign instead.
Limits still apply
Sending stops with a clear error if you have no emails left, your domain isn't verified, or a daily or new-sender limit is reached. API emails are not held back by domain warm-up, but they count toward the domain's volume. Requests are limited to 600 a minute per key.
Keep your key secret
Anyone with the key can send as your domain. Use Send only keys for sending, revoke a key from Settings if it leaks, and never put it in browser code.
Questions
How do I send email with an API?
Verify a domain, create an API key in Settings, then POST a JSON body with to, from, subject and html to /v1/emails with an Authorization Bearer header. The response gives you an email id.
What is the difference between transactional and marketing email?
Transactional email is a one-to-one message triggered by a person's action, such as a receipt or a password reset. Marketing email is a campaign sent to a list. In Hemero the first goes through the API, the second through campaigns.
Can I send the same email twice by mistake?
Not if you send an Idempotency-Key header. A repeated request with the same key returns the first email instead of sending again.
How do I know whether an email was delivered or bounced?
Read its status with GET /v1/emails/:id, or add a webhook endpoint and listen for email.delivered, email.bounced and similar events.
Is there an OpenAPI file?
Yes, at hemero.app/openapi.json. It describes the public API and is ready to import into most API clients.
Can I send from any address?
Only from addresses on a domain you have verified in Hemero. A request from any other domain is rejected.
Ready to send from your code? Create an account, verify your domain and make your first API request.