Skip to content

Documentation

Send email from a Supabase Edge Function.

A Deno function that sends a message, called from your app or a database webhook.

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.

Set the secret

Store the key as a function secret. It is available to your functions as an environment variable and never reaches the browser.

Terminal
supabase secrets set MAILTRUSS_API_KEY=ms_live_…

The function

Edge Functions run on Deno, which imports npm packages with the npm: prefix. By default Supabase requires a valid JWT on the request, so only your signed-in users or your own backend can call it. The CORS headers let a browser app call it.

supabase/functions/send-welcome/index.ts
import { MailClient, MailError } from "npm:mailtruss";
​
const mail = new MailClient({ apiKey: Deno.env.get("MAILTRUSS_API_KEY")! });
const cors = { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Headers": "authorization, x-client-info, apikey, content-type" };
const escapeHtml = (s: string) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
​
Deno.serve(async (req) => {
if (req.method === "OPTIONS") return new Response("ok", { headers: cors });
const { email, name } = await req.json();
try {
const { id } = await mail.emails.send(
{ from: "Acme <hello@yourdomain.com>", to: email, subject: "Welcome to Acme", html: `<p>Hi ${escapeHtml(name)}, thanks for signing up.</p>` },
{ idempotencyKey: `welcome:${email}` },
);
return Response.json({ id }, { headers: cors });
} catch (e) {
if (e instanceof MailError) return Response.json({ error: e.code }, { status: 502, headers: cors });
throw e;
}
});

Deploy and call it

Deploy with the CLI, then call it from your app with the Supabase client.

Terminal and app
supabase functions deploy send-welcome
​
// in your app
const { data, error } = await supabase.functions.invoke("send-welcome", {
body: { email: "ada@example.com", name: "Ada" },
});

For Supabase Auth's own emails

Sign-up confirmations and password resets can go through Mailtruss too: see the [Supabase Auth guide](/docs/guides/supabase-auth).

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