Herald docs
Herald sends your product’s email: one API and SMTP for every message, from sign-in codes and receipts to launches and newsletters. These pages take you from a key to your first delivered email, then through domains, webhooks and the full API.
NodeSend with the SDK in five minutes.
Next.jsRoute handlers, React Email and webhooks.
SMTPPoint any app’s SMTP settings at Herald.
Coming from ResendKeep your code, change one setting.
How Herald is organised
- A project is one product: Mentor, Sidekick or Hallelo. Its domains, keys, contacts, templates and suppression list are its own, and no other project can reach them.
- Live and test. Every key is one or the other:
hrld_live_…orhrld_test_…. Test keys never send to anyone; their mail lands in the project’s Test inbox in Console, and they can’t read live data. - Two lanes. Dispatches (transactional email: one person, sent the moment something happens) and Proclamations (marketing: an audience, on a schedule) travel apart, so a newsletter never slows a sign-in code. In the API they’re the
stream:transactional, the default, ormarketing.
The API
| Base URL | https://api.heraldmail.dev |
| Authentication | Authorization: Bearer hrld_live_… |
| Format | JSON in, JSON out |
| Errors | RFC 9457 problems, with Resend’s name, statusCode and message |
| Rate limit | 50 requests a second per key, in the RateLimit headers |
| Lists | Newest first: ?limit= (up to 100) and ?after=<id>, with has_more |
| Retries | Send Idempotency-Key with a send, and a retry is never a second email |
Every response carries an x-request-id; quote it when you ask about a call. The whole API, generated from the same schemas that check each request, is in the API reference.
Keys
Make keys in Console, on the project’s API keys page. Each key is shown once. Give each app its own, and only what it needs:
- Sending only: for apps. It can send, and nothing else.
- Sending and reading: it can also read emails and their events.
- Full access: everything the API can do, including making and revoking keys. Console asks for your passkey before it makes one, and tells the project’s owners.
A key can also be limited to some of the project’s domains, to a list of addresses it may be used from, and to an expiry date.