Skip to content

Documentation

Send email from Astro.

An API endpoint that sends a message. It needs on-demand rendering, because it runs per request.

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

Add the client. Endpoints run on the server, so the key stays private.

Terminal
npm install mailtruss

The endpoint

Set prerender to false so the route runs on request (your project needs a server adapter). The key is read from a server-side environment variable.

src/pages/api/contact.ts
import type { APIRoute } from "astro";
import { MailClient, MailError } from "mailtruss";
​
export const prerender = false;
const escapeHtml = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
​
export const POST: APIRoute = async ({ request }) => {
const { email, message } = await request.json();
if (typeof email !== "string" || !email.includes("@") || typeof message !== "string" || !message) {
return Response.json({ error: "Enter your email and a message." }, { status: 422 });
}
const mail = new MailClient({ apiKey: import.meta.env.MAILTRUSS_API_KEY });
try {
const { id } = await mail.emails.send({
from: "Site <hello@yourdomain.com>", to: "you@yourdomain.com", reply_to: email,
subject: "New message from the site", html: `<p>${escapeHtml(message)}</p>`,
});
return Response.json({ id });
} catch (e) {
if (e instanceof MailError) return Response.json({ error: e.code }, { status: 502 });
throw e;
}
};

Where the key lives

Put MAILTRUSS_API_KEY in .env for local work and in your host's environment settings for production. Do not prefix it with PUBLIC_: that would send it to the browser. With the Cloudflare adapter, runtime secrets come from the adapter's runtime object instead of import.meta.env: see Astro's documentation for your adapter.

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