Skip to content

Documentation

Send email from Nuxt.

A server route that sends a message, with the key in private runtime config.

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 to your Nuxt project.

Terminal
npm install mailtruss

The key, as private runtime config

A runtime config key outside public is only available on the server. Nuxt fills it from an environment variable named NUXT_ plus the key in upper snake case, so mailtrussApiKey is read from NUXT_MAILTRUSS_API_KEY.

nuxt.config.ts
export default defineNuxtConfig({
runtimeConfig: {
mailtrussApiKey: "", // set NUXT_MAILTRUSS_API_KEY in the environment
},
});

The server route

A file named contact.post.ts under server/api answers POST /api/contact.

server/api/contact.post.ts
import { MailClient, MailError } from "mailtruss";
​
const escapeHtml = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
​
export default defineEventHandler(async (event) => {
const { email, message } = await readBody<{ email?: string; message?: string }>(event);
if (!email?.includes("@") || !message) throw createError({ statusCode: 422, statusMessage: "Enter your email and a message." });
​
const mail = new MailClient({ apiKey: useRuntimeConfig(event).mailtrussApiKey });
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 { id };
} catch (e) {
if (e instanceof MailError) throw createError({ statusCode: 502, statusMessage: "We could not send that. Try again in a minute." });
throw e;
}
});

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