API reference

How to send email through Hamanimail from your own domain.

The Hamanimail sending API lets your app send email from your own domain over a simple HTTPS JSON interface. Every request and response is application/json.

You only need this if you want your software to send email — receipts, sign-up codes, notifications, newsletters. To read and write mail as a person, use your inbox. No API key required.

Base URL

https://api.hamanimail.com

New here? Send your first email in five minutes.

Guides

Page	What it covers
Quickstart	key, domain, first send
Authentication	bearer keys, scopes, rotation, what to do if one leaks
Libraries and examples	working send code in Node, Python, PHP, Ruby, Go and curl
Domains	the DNS records, what each does, and why you should not publish the MX by accident
Sending responsibly	suppression, the Spam Act, warm-up, and how sending gets paused

Reference

Page	What it covers
Emails	`POST /v1/send`, every parameter, attachments, idempotency, batches
Scheduled sends	`sendAt`, listing and cancelling
Templates	saved, localised, variable-filled email
Email log	`GET /v1/emails` — what happened to everything you sent
Webhooks	events, payloads, and verifying the signature
Errors	every error code, and which ones are safe to retry
Limits	the real numbers

The shortest possible example

curl https://api.hamanimail.com/v1/send \
  -H "Authorization: Bearer hme_yourkeyid_yoursecret" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Your Business <hello@yourbusiness.com.au>",
    "to": "customer@example.com",
    "subject": "Welcome",
    "category": "transactional",
    "html": "<p>Thanks for signing up.</p>"
  }'

{ "status": "queued", "messageId": "…", "idempotencyKey": "…" }

Three things worth knowing before you build

A 202 means queued, not delivered. Delivery is reported afterwards, through webhooks and the email log. Do not tell your customer their email arrived because the API returned 202.

Always send an idempotencyKey. It is the difference between a retry that is safe and one that charges your customer twice — and it is what makes a 503 recoverable. See Safe retries.

Unknown fields are rejected, not ignored. A typo in a field name returns 400 naming it, rather than silently sending an email missing the part you meant to include.

Conventions

All times are Unix milliseconds unless the field is named as ISO-8601.
All monetary and volume figures in your workspace are in AUD, GST included.
error codes are stable. message text is not — never match on it.
Anything not documented on these pages is not part of the public API, and may change without notice.