Skip to main content

​
Configure an email provider Action using the Auth0 Dashboard

To use the Auth0 Dashboard to configure your tenant with a custom email provider Action:
  1. Go to Auth0 Dashboard > Branding > Email Provider.
  2. Enable the Use my own email provider toggle.
  3. In the Email Provider Section, select Custom Provider.
  4. In the From field, enter the default email address from which emails are sent.
  5. In the code editor, write your Action code to deliver messages to your email provider. Use your provider’s documentation on their API or SMTP connection details. In the left menu of the code editor, you can click the key icon to add secrets (for example, to authenticate with an API) and click the box to add dependencies.
  6. When you’re finished writing the Action, click Save to deploy it.
To test your configuration, click Send Test Email. Like other Actions, you can use the Management API to manage the Action and its versions. All Actions are subject to the same limitations.

​
Configure an email provider Action using Terraform

The Terraform Auth0 provider uses the Auth0 Management API to perform actions on the Auth0 platform. You can use the Terraform Auth0 provider to create a custom email provider Action and configure your tenant to use it.

​
1. Unbind or delete conflicting Actions

You can have at most one Action bound to the custom-email-provider trigger. If your tenant is already configured with a custom email provider Action, reset it before creating a new email provider Action with Terraform:
  1. Go to Auth0 Dashboard > Branding > Email Provider.
  2. In the Email Provider section, click Custom Provider.
  3. Below the Actions code editor, click Reset.
You can check if you have other deployed actions bound to the custom-email-provider trigger using the Management API:
  1. List your Actions to identify any duplicate Actions.
  2. Update their trigger bindings or delete the Actions.

​
2. Create a new email provider Action

Use the Terraform auth0_action resource to create an Action that supports the custom-email-provider trigger. Set deploy = true to immediately create a new version of the Action. 
resource "auth0_action" "custom_email_provider" {
  name    = "Custom Email Provider"
  runtime = "node20"
  deploy  = true
  code    = <<-EOT
    /**
    * Handler to be executed while sending an email notification
    * @param {Event} event - Details about the user and the context in which they are logging in.
    * @param {CustomEmailProviderAPI} api - Methods and utilities to help change the behavior of sending a email notification.
    */
    exports.onExecuteCustomEmailProvider = async (event, api) => {
      // Code goes here
      return;
    };
  EOT
  supported_triggers {
    id      = "custom-email-provider"
    version = "v1"
  }
}
In the function stub, write your Action code to deliver messages to your email provider. Use your provider’s documentation on their API or SMTP server details.

​
3. Bind the Action to the email provider trigger

Use the Terraform auth0_trigger_action resource to bind the Action to the custom-email-provider trigger: 
resource "auth0_trigger_action" "custom_email_provider" {
  trigger = "custom-email-provider"
  actions {
    id           = auth0_action.custom_email_provider.id
    display_name = auth0_action.custom_email_provider.name
  }
   depends_on = [
    auth0_action.custom_email_provider
  ]
 }

​
4. Configure your tenant’s email provider with the Action

Use the Terraform auth0_email_provider resource to configure your tenant to use the email provider Action: 
resource "auth0_email_provider" "custom_email_provider" {
  name                 = "custom"
  enabled              = true
  default_from_address = "[email protected]"
  credentials {}
  depends_on = [
    auth0_trigger_actions.custom_email_provider
  ]
If you create a new email provider Action with Terraform and it does not take effect, you may have already had a deployed Action bound to the custom-email-provider trigger. To troubleshoot and fix this issue, follow the first step of this article to unbind or delete conflicting Actions.

​
Example Email Provider Action

This is an example Action for the custom-email-provider trigger. In this code sample, the function onExecuteCustomEmailProvider takes two arguments from the custom-email-provider event object: event, which contains information about the user and the context of the notification, and api, which provides helper methods for custom behavior while sending notifications. 
/**
 * Handler to be executed while sending an email notification.
 * @param {Event} event - Details about the user and the context in which they are logging in.
 * @param {CustomEmailProviderAPI} api - Methods and utilities to help change the behavior of sending an email notification.
 */
exports.onExecuteCustomEmailProvider = async (event, api) => {
  // Define the email payload
  const emailPayload = {
    from: {
      name: "Test Sender",
      email: "[email protected]"
    },
    to: [{ email: event.user.email }],
    subject: event.notification.message_type,
    html: event.notification.html,
    text: event.notification.text,
  };
  try {
    // Make the API call to send the email
    const response = await fetch('https://api.example.com/send-email', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${event.secrets.api_key}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(emailPayload),
    });
    if (response.ok) {
      console.log('Email sent successfully');
    } else if (response.status >= 500) {
      api.notification.retry(
        `Internal Server Error received from Messaging Proxy. Status code: ${response.status}.`
      );
      return;
    }
  } catch (error) {
    console.error(`Error sending email: ${error.message}`);
    api.notification.drop(`An unexpected error occurred. Error: ${error.message}`);
  }
  return;
};
To learn more about Actions, read Understand How Auth0 Actions Work.