Netlify Email Integration

Netlify Labs feature

This feature is available through Netlify Labs, which helps us collect early feedback on newer features. You may notice some changes to this feature’s functionality as we improve your experience. Learn more in our Netlify Labs doc.

The Netlify Email Integration connects your Netlify site with popular, API-driven email services and allows you to manage version-controlled email templates alongside the rest of your project code. Use the Netlify Email Integration to generate serverless function email handlers that populate custom email templates and send emails using a specified email API provider.

The Netlify Email Integration is enabled by default in Netlify Labs. You can visit Netlify Labs to deactivate it for your Netlify user.

# Before you begin

  • Set up an account with one of the supported email providers listed below. The integration uses an email API.
  • Ensure your account is verified by the email API provider.
  • Ensure that you have provided authorization to send emails from the email address you wish to use as the sender.
  • Note your API key from your email API provider.

# Supported email providers

You can use the Netlify Email Integration to connect your Netlify site with email APIs from these providers:

# Enable Netlify Email Integration for your site

The Netlify Email Integration is powered by the Netlify Emails build plugin. Follow these steps to enable it for your site using the Netlify UI or file-based installation.

# Enable with the Netlify UI

  1. In the Netlify UI, under Sites, select the site you’d like to enable the Netlify Email Integration on.

  2. Visit Site settings > Emails for your site.

  3. Select Enable emails. This adds the Netlify Emails plugin to your site.

  4. Complete the setup:

    • select an Emails provider
    • enter an Emails provider API key
    • optionally, set a custom Emails directory

    Then select Save.

  5. Deploy your site so that you can use the plugin.

# Enable with netlify.toml

  1. Add the plugin to a netlify.toml file stored in your site’s base directory.

    [[plugins]]
      package = "@netlify/plugin-emails"
    
  2. Add the required environment variables for the plugin. We recommend using the Netlify UI, CLI, or API for this step.

  3. Deploy your site so that you can use the plugin.

# Required environment variables

When enabling the plugin using netlify.toml, certain environment variables are required to complete initial configuration. If you have the option to set specific scopes for your environment variables, the scope must include both Builds and Functions to be available to the build system and to serverless functions.

Variable Name Description Required
NETLIFY_EMAILS_PROVIDER Valid values:
mailgun
sendgrid
postmark
Yes
NETLIFY_EMAILS_PROVIDER_API_KEY API key issued by the email provider Yes
NETLIFY_EMAILS_MAILGUN_DOMAIN Domain used by Mailgun Yes, if Mailgun
NETLIFY_EMAILS_DIRECTORY The default directory path is ./emails but can be changed by setting this variable No

An authentication secret is automatically generated

Netlify automatically generates a value for a NETLIFY_EMAILS_SECRET environment variable, but you can edit it if needed. This value is a unique secret used to authenticate that a request to the email API provider is genuine.

# Add email templates

To add an email template, add a file at the appropriate location and set up the contents and styling for the template.

# Add a template file

To add an email template to your project:

  1. Create an emails directory in the base directory for your project.
  2. Create a subdirectory for your template. The subdirectory name should represent the expected route of your template.
  3. Create an index.html file within the subdirectory.

Here’s an example file structure for a subscribed email: /emails/subscribed/index.html:

repository-root or base directory/
├─ emails/
│  └─ subscribed/
│   └─ index.html
└─ 

The default emails directory is YOUR_BASE_DIRECTORY/emails.

To optionally configure a custom emails directory, set the NETLIFY_EMAILS_DIRECTORY environment variable or update the directory value in the Netlify UI:

  1. Visit Site settings > Emails > Email Integration configuration.
  2. Select Edit settings and enter a custom Emails directory.

# Add HTML to the template

The template file accepts HTML and must include <html> and <body> tags.

If you want to use variables in your email template, you can use handlebars.js syntax and pass the arguments in the request. The variable values will be injected when the email is triggered.

Here’s a sample email with a parameter:

<html>
  <body>
    <h1>Welcome, {{name}}</h1>
    <p>We hope you enjoy our super simple emails!</p>
    <p>Thanks for subscribing!</p>
  </body>
</html>

# Style the template

You can also add custom styling to your templates by adding inline CSS blocks using the style attribute inside the HTML elements of the template index.html file.

<html>
  <body
    style="
      font-family: 'Open Sans', 'Helvetica Neue', sans-serif;
      margin: 0 auto;
    "
  >
    <div
      style="
        background-color: white;
        display: inline-block;
        text-align: center;
      "
    >
      <h1>{{name}} has RSVP'd</h1>
      <button style="border-radius: 10px;">
        Visit dashboard
      </button>
    </div>
  </body>
</html>

# Preview email templates

You can preview your email templates during the development process. The preview also generates a fetch snippet that contains the code required to send a request to the email handler for the template you are previewing. Use the Netlify CLI to launch a preview and generate this code.

  1. Ensure you have the latest version of Netlify CLI installed:

    npm install netlify-cli -g
    
  2. Build your project.

    netlify build
    
  3. Launch Netlify Dev to start a development environment that can run your email preview:

    netlify dev
    
  4. Visit http://localhost:8888/.netlify/functions/emails/_preview to launch the preview.

    The preview endpoint is not available in production and is only made available locally through Netlify Dev.

  5. Select your email template.

    open preview of email template.

Test email triggering

Learn more about the local development process in the Test locally section below.

# Trigger an email from your code

When you preview your email template using the process above, Netlify generates a fetch code snippet.

preview of email template with generated fetch function.

To trigger an email directly from your project code, copy and paste this snippet into your project and populate the parameters for your email.

# Create a Netlify Function to send the email

Because the snippet generated in the preview contains an environment variable, NETLIFY_EMAILS_SECRET, we recommend pasting the code snippet into a Netlify Function to avoid sharing sensitive information in client-side code.

You can learn more about the format of a Netlify Function call on the Build functions page. The function file should be in your netlify/functions directory. Following the fetch code example below, this example file’s path would be netlify/functions/triggerSubscribeEmail.ts.

import { Handler } from "@netlify/functions";
import fetch from "node-fetch";

const handler: Handler = async function (event) {
  if (event.body === null) {
    return {
      statusCode: 400,
      body: JSON.stringify("Payload required"),
    };
  }

  const requestBody = JSON.parse(event.body) as {
    subscriberName: string;
    subscriberEmail: string;
    inviteeEmail: string;
  };

  //automatically generated snippet from the email preview
  //sends a request to an email handler for a subscribed email
  await fetch(`${process.env.URL}/.netlify/functions/emails/subscribed`, {
    headers: {
      "netlify-emails-secret": process.env.NETLIFY_EMAILS_SECRET as string,
    },
    method: "POST",
    body: JSON.stringify({
      from: requestBody.inviteeEmail,
      to: requestBody.subscriberEmail,
      subject: "You've been subscribed",
      parameters: {
        name: requestBody.subscriberName,
        email: requestBody.subscriberEmail,
      },
    }),
  });

  return {
    statusCode: 200,
    body: JSON.stringify("Subscribe email sent!"),
  };
};

export { handler };

Next, you'll add an event in your code to call this Netlify Function.

# Call the Netlify Function from an event

There are many approaches you can take to triggering an email. For example:

  • a user clicks a button requesting information, subscribing to a newsletter, or updating their profile
  • a user scrolls to the bottom of a blog post so you trigger an email to send them more information on that post subject or other posts
  • a data event has reached a certain amount and you would like an email sent to notify your users

Here’s an example of the code to attach the email trigger to a Subscribe button in a Next.js app. In this React example, the parameters for the template are set using user input from the form on the page. With this process, you can populate the parameters of your email templates with any data being passed to your site, like a form or data from API calls to a user database.

export default function Subscribe() {
  const handleSubmit = async (event: React.FormEvent<HTMLFormElement>) => {
    event.preventDefault();
    const target = event.target as typeof event.target & {
      name: { value: string };
      email: { value: string };
    };

    const data = {
      subscriberName: target.name,
      subscriberEmail: target.email,
    };
    //call to the Netlify Function you created
    fetch("./.netlify/functions/triggerSubscribeEmail", {
      method: "POST",
      body: JSON.stringify({
        subscriberName: data.subscriberName,
        subscriberEmail: data.subscriberEmail,
        inviteeEmail: "info@netlify.com",
      }),
    });
  };
  return (
    <div className="subscribe-form-container">
      <form onSubmit={handleSubmit}>
        <label htmlFor="name">Name</label>
        <input type="text" id="name" name="name" required />
        <label htmlFor="email">Email</label>
        <input type="text" id="email" name="email" required />
        <button type="submit">Subscribe</button>
      </form>
    </div>
  );
}

When the event is triggered, this invokes the Netlify Function and the fetch call to an email handler. This handler prompts the email API service you configured to send the email.

# Test locally

You can use the Netlify CLI to trigger an email during the development process to test out your code before deploying.

  1. Launch Netlify Dev to start a development environment that can run your code for triggering the email:

     netlify dev
    
  2. While the Netlify Dev environment is running, trigger a test of the email by visiting the URL below, replacing YOUR_EMAIL_TEMPLATE_SUBDIRECTORY with a valid value from your project.

    http://localhost:8888/.netlify/functions/emails/YOUR_EMAIL_TEMPLATE_SUBDIRECTORY

    For example, for a subscribed email stored in your project at /emails/subscribed/index.html, visit http://localhost:8888/.netlify/functions/emails/subscribed to trigger the email.

    The email will be sent using the email API service you configured.

# Feedback

We welcome your feedback on the Netlify Email Integration. Fill out our survey to share your thoughts or ideas.