Configure a Custom Email Provider with Terraform

You can configure a custom email provider with the Terraform Auth0 provider. The Terraform Auth0 provider is used to interact with the Auth0 Management API in order to configure an Auth0 Tenant. To learn more, review Terraform’s Auth0 Provider documentation.

If you are using Terraform to configure a custom email provider, delete your existing Auth0 tenant custom email provider.
Auth0 has a maximum limit of one Action for Actions associated with the following triggers: custom-phone-provider and custom-email-provider.

The following steps outline how to a custom email provider using Terraform:

1. Create an auth0_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"
  }
}

Was this helpful?

In order to bind a Terraform auth0_action to an auth0_trigger_action, set the auth0_action to deploy = true. To learn more, read Terraform's auth0_action documentation.

2. Bind the auth0_action to the custom-email-provider auth0_trigger_action:

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
  ]

Was this helpful?

3. Configure the auth0_email_provider resource to use the auth0_action:

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
  ]

Was this helpful?

To learn more, read Terraform’s auth0_email_provider documentation.

Troubleshoot

Scenario: Custom email provider configured using Terraform is not taking effect, and the Auth0 Dashboard displays a different Action.

You may have multiple custom provider Actions with deploy: true. Auth0 has a maximum limit of one Action for Actions associated with the following triggers: custom-phone-provider and custom-email-provider.

If you encounter this scenario, it’s recommended that you list your Actions to identify any duplicates to delete.
If you encounter this scenario after managing your custom providers through multiple methods (Terraform, Auth0 Dashboard, Management API, and/or Auth0 SDKs) it is advisable to reset the custom provider configuration. We recommend you refrain from using multiple methods to manage your custom provider.

To reset the custom email provider, navigate to Auth0 Dashboard > Branding and select Email Provider. Then, select the Reset button to restore your custom provider to its default

Customize

Configure a Custom Email Provider with Terraform

Troubleshoot