Use Multiple Email Templates for Headless Flows

By default, for the verification email sent to end users, the Headless Registration Flow, Headless Passwordless Login Flow, and Headless Forgot Password Flow use the email template specified in your Experience Cloud site’s email settings. To expand your email template options, create an email template allowlist using Metadata API. For example, create an allowlist with multiple, custom email templates that each provide a different branding experience.

Required Editions

Available in: Enterprise, Unlimited, and Developer Editions

You configure email template allowlists at the Experience Cloud site level, so an allowlist applies to headless flows configured with that Experience Cloud site. If you create an allowlist, include an emailtemplate parameter in your initial request to the headless API for the flow you’re building. The emailtemplate parameter can include only allowlisted email templates. You can send one email template per flow.

For headless registration and passwordless login, if you don’t include an emailtemplate parameter, Salesforce defaults to using the email template configured in your Experience Cloud site settings. If there’s no template configured, Salesforce uses a default one-time password (OTP) email template.
For the Headless Forgot Password Flow, you must explicitly enable email template allowlisting in your Experience Cloud site settings. If you don’t enable it, the allowlist doesn’t apply, and the emailtemplate parameter can include any email template in the org.

To configure an email template allowlist, follow these high-level steps.

Create custom email templates. See Customize Email Sent from Experience Cloud Sites for Email Verification.
For each email template, use Metadata API to create a NetworkEmailTmplAllowlist metadata type. Add your custom email template IDs to the emailTemplate field.
For more information about working with Metadata API, see the Metadata API Developer Guide.
The NetworkEmailTmplAllowlist metadata type is a subtype of the NetworkAuthApiSettings metadata type that represents your Experience Cloud settings for headless identity, which is itself a subtype of the Network metadata type that represents your Experience Cloud site. Here’s an example metadata definition for the Network metadata type. Most of the definition is abridged to highlight the allowlist fields. For a full definition, see Network in the Metadata API Developer Guide.
```
<?xml version=”1.0” encoding=”UTF-8”?>
<Network xmlns="http://soap.sforce.com/2006/04/metadata">
  […]
    <networkAuthApiSettings>
      [...]
      <emailTmplsAllowlist>
            <emailTemplate>unfiled$public/SalesNewCustomerEmail</emailTemplate>
      </emailTmplsAllowlist>
        <emailTmplsAllowlist>
            <emailTemplate>unfiled$public/SUPPORTSelfServiceNewCommentNotification</emailTemplate>
        </emailTmplsAllowlist>
        <emailTmplsAllowlist>
            <emailTemplate>unfiled$public/SupportCaseAssignmentNotification</emailTemplate>
        </emailTmplsAllowlist>
    </networkAuthApiSettings>
</Network>
```
For the Headless Forgot Password Flow, opt in to email template allowlisting in your Experience Cloud settings. See Configure Experience Cloud Settings for the Headless Forgot Password Flow.
Configure your headless flow and include the emailtemplate parameter in your requests as directed. See these resources.
- For headless registration, see Headless Registration Flow for Public Clients and Headless Registration Flow for Private Clients.
- For headless passwordless login, see Headless Passwordless Login Flow for Public Clients and Headless Passwordless Login Flow for Private Clients.
- For the Headless Forgot Password Flow, see Headless Forgot Password Flow for Customers and Partners.