Send email from Netlify

Send transactional email from a site on Netlify (Netlify Functions, Edge Functions, or a framework's server routes) with the Groundmail API. Your code reads the API key from the GROUNDMAIL_API_KEY environment variable.

Prerequisites

• A Groundmail account with a verified sending domain. A subdomain such as mail.yourdomain.com works well.
• A site on Netlify.

Connect Netlify

1. In the dashboard, open Integrations → Netlify and click Connect Netlify.
2. Netlify asks you to authorize Groundmail. Click Authorize.
3. Back in Groundmail, pick a site and click Add GROUNDMAIL_API_KEY. Groundmail creates a sending key and sets it as GROUNDMAIL_API_KEY on that site for every deploy context (production, deploy previews, branch deploys and local netlify dev). Leave Redeploy now on to start a production build, so the site picks it up straight away; otherwise it applies on the next deploy.

If the site already has GROUNDMAIL_API_KEY, Groundmail asks before replacing it. The key never appears on screen. It's listed under API keys as "Netlify: site name", where you can revoke it.

Netlify doesn't let apps limit their access to particular sites, so Groundmail only reads your site list, writes the one variable you ask for, and writes DNS records when you click Apply DNS. Disconnect in Groundmail forgets the connection; to remove Groundmail from your Netlify account too, go to User settings → Applications in Netlify. Sites you already set up keep their key.

By hand

Create an API key under API keys, then in Netlify open Site configuration → Environment variables, add GROUNDMAIL_API_KEY with the key as its value, and redeploy.

Set up your domain's DNS

If your sending domain uses Netlify DNS, the same connection writes its records:

1. Add the domain under Domains.
2. On its DNS tab, click Apply DNS (Netlify). Groundmail adds the SPF, DKIM, DMARC and return-path records to the Netlify DNS zone, merging into an existing SPF record, then checks them.

Netlify DNS can't edit a record in place, so when a value changes Groundmail adds the new record and then removes the old one. Subdomains such as mail.yourdomain.com work when their parent domain's zone is on Netlify.

Send an email

Netlify Function (Node.js)

npm install groundmail

// netlify/functions/welcome.mjs
import { Groundmail } from 'groundmail'

const groundmail = new Groundmail(process.env.GROUNDMAIL_API_KEY)

export default async (req) => {
  const { email } = await req.json()
  await groundmail.emails.send({
    from: 'App <no-reply@mail.yourdomain.com>',
    to: email,
    subject: 'Welcome',
    html: '<p>Thanks for signing up.</p>',
  })
  return new Response('ok')
}

Frameworks deployed on Netlify (Next.js, Astro, SvelteKit, Remix, Nuxt) read the same variable in their server routes. See the Node.js guide and the Next.js guide. Any other runtime can call POST https://api.groundmail.dev/emails with the key: see the API reference.

Troubleshooting