> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-actions-triggers-prototype.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure an Email Provider with a Customized Action

> Write an Action that delivers messages to your email provider from either the Auth0 Dashboard or Terraform Auth0 provider, and implement custom logic for your use case.

## 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](https://manage.auth0.com/#/templates/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](https://auth0.com/docs/api/management/v2/actions/get-actions) to manage the Action and its [versions](/docs/customize/actions/manage-versions). All Actions are subject to the same [limitations](/docs/customize/actions/limitations).

## Configure an email provider Action using Terraform

The [Terraform Auth0 provider](https://registry.terraform.io/providers/auth0/auth0/latest/docs) uses the [Auth0 Management API](https://auth0.com/docs/api/management/v2) 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](https://manage.auth0.com/#/templates/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](https://auth0.com/docs/api/management/v2/actions/get-actions) to identify any duplicate Actions.
2. [Update their trigger bindings](https://auth0.com/docs/api/management/v2/actions/patch-bindings) or [delete the Actions](https://auth0.com/docs/api/management/v2/actions/delete-action).

### 2. Create a new email provider Action

Use the [Terraform `auth0_action` resource](https://registry.terraform.io/providers/auth0/auth0/latest/docs/resources/action) to create an Action that supports the `custom-email-provider` trigger. Set `deploy = true` to immediately create a new version of the Action.

```terraform lines theme={null}
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](https://registry.terraform.io/providers/auth0/auth0/latest/docs/resources/trigger_action) to bind the Action to the `custom-email-provider` trigger:

```terraform lines theme={null}
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](https://registry.terraform.io/providers/auth0/auth0/latest/docs/resources/email_provider) to configure your tenant to use the email provider Action:

```terraform lines theme={null}
resource "auth0_email_provider" "custom_email_provider" {
  name                 = "custom"
  enabled              = true
  default_from_address = "accounts@example.com"
  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](#1-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](/docs/customize/email/configure-a-custom-email-provider/action-triggers-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.

```javascript lines expandable theme={null}
/**
 * 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: "sender@example.com"
    },
    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](/docs/customize/actions/actions-overview).