Skip to content

Documentation

Send email from a Hono app.

A Hono route that sends a message, written once for Workers, Bun and Node.

Before you start

You need a verified sending domain (see Domains) and an API key (under API keys in the dashboard; it is shown once). Keep the key in an environment variable on your server, never in code that runs in a browser or an app.

Install

The client uses fetch, so it runs wherever Hono does.

Terminal
npm install mailtruss hono

The route

On Cloudflare Workers the key is a binding on c.env. On Bun or Node, read process.env instead (see the note below). The route escapes user input and turns a Mailtruss error into a clean 502.

src/index.ts
import { Hono } from "hono";
import { MailClient, MailError } from "mailtruss";
​
type Env = { Bindings: { MAILTRUSS_API_KEY: string } };
const app = new Hono<Env>();
const escapeHtml = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
​
app.post("/contact", async (c) => {
const { name, email, message } = await c.req.json<{ name: string; email: string; message: string }>();
const mail = new MailClient({ apiKey: c.env.MAILTRUSS_API_KEY });
try {
const { id } = await mail.emails.send(
{
from: "Site <hello@yourdomain.com>", to: "you@yourdomain.com", reply_to: email,
subject: `Message from ${name}`,
html: `<p>${escapeHtml(message)}</p>`,
},
{ idempotencyKey: `contact:${email}:${message.length}` },
);
return c.json({ id });
} catch (e) {
if (e instanceof MailError) return c.json({ error: e.code, message: e.message }, 502);
throw e;
}
});
​
export default app;

The key

On Workers, store it as a secret: npx wrangler secret put MAILTRUSS_API_KEY. On Bun or Node, set the MAILTRUSS_API_KEY environment variable and replace c.env.MAILTRUSS_API_KEY with process.env.MAILTRUSS_API_KEY.

Try it without sending real mail

Send to delivered@mailtruss.test first. It works before any domain is verified and reaches no real mailbox, so you can check your code and see the recorded timeline. Then try bounced@mailtruss.test to see what a bounce looks like. All the test addresses are listed under Sending.

See what happened

Open the message under Emails in the dashboard: it shows the recorded timeline, what each event proves, and a diagnosis if something went wrong. Or fetch it with GET /api/v1/emails/:id/events. To be told as it happens, add a webhook.

If it fails

API requests answer with an error name and message. The common ones:

  • 403 invalid_api_key or 401 missing_api_key: the key is wrong, revoked or not sent. Send it as Authorization: Bearer ms_live_….
  • 403 domain_not_verified: the from address is on a domain that is not verified. Publish the DNS records and re-check.
  • 422 validation_error: fix the field the message names. Nothing was sent and no quota was used.
  • 429 rate_limit_exceeded: back off for the Retry-After header. See rate limits.

Problems that happen after a message is accepted (bounces, complaints) are explained under delivery errors.

Other guides

Last updated

Something wrong or unclear on this page?

Report an issue