> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/email-challenge-template.md).

# Email challenge template

Choose the email template of the identity-confirmation email sent during an enrolment, or skip the email, with runtime.emailAccountChallenger.templateFinder.

When the tenant requires customers to confirm their identity, an enrolment does not create anything straight away: The Wallet Crew sends an email with a link, and the enrolment continues when the customer opens it. This identity-confirmation email always uses the template configured on the email account challenger. The template finder lets a tenant script choose another template for each email, based on what the enrolment carries, or decide that no email should be sent at all. This page is the reference for `runtime.emailAccountChallenger.templateFinder`.

The template finder only chooses the template name. Sending the email through another service is the job of the [email engine](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/email-engine.md); emails sent by the `mail` steps of a registration flow are not concerned.

<details>

<summary><strong>Real-world examples</strong></summary>

* A brand sends a "welcome back" email to customers its CRM already knows, and the standard email to new ones.
* A tenant with several markets picks the template of the customer's market.
* A brand skips the email when an external system says the customer has already completed the enrolment elsewhere.

</details>

## Registration

The key is `runtime.emailAccountChallenger.templateFinder`. It only has an effect when the tenant has an email account challenger (the setting that sends the identity-confirmation email), configured in `server/account.yml`:

```yaml
checkInSecurityMode: partial
accountChallengers:
  - type: email
    templateName: confirm-identity
```

`templateName` is the default template, which the script receives and can keep. The optional `identifiers` list of the challenger restricts which identifiers count when the challenger checks that a customer exists.

The minimal skeleton is:

```js
export default function (context) {
  context.register('runtime.emailAccountChallenger.templateFinder', {
    GetEmailTemplate: async (data, defaultTemplateName) => defaultTemplateName
  });
}
```

## When it runs

The script runs each time the email account challenger is about to send its email, inside the enrolment request (`POST /api/{tenantId}/customer`). Whether that happens depends on `checkInSecurityMode` and on the caller: with `full` (the default), every enrolment by an unauthenticated caller receives the email; with `partial`, only an enrolment whose customer already exists does, after the customer providers have looked the customer up; with `none` and `noIdentification`, no identity-confirmation email is sent. An account without an email address receives no email and the script is not called.

## Handlers

| Method             | Parameters                    | Returns                                         | Required |
| ------------------ | ----------------------------- | ----------------------------------------------- | -------- |
| `GetEmailTemplate` | `data`, `defaultTemplateName` | a template name, `null`, or a promise of either | Required |

`data` holds the values the email will be rendered from: the account as submitted and completed by the customer providers (`data.email`, `data.firstName`, identifiers under `id.<key>` such as `data['id.crm.customerId']`), plus `data.authenticationToken`, the token of the link that continues the enrolment. `defaultTemplateName` is the `templateName` of the challenger.

{% hint style="warning" %}
`data.authenticationToken` lets whoever holds it continue the enrolment as the customer. It must never be logged; see [Email engine](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/email-engine.md#errors-and-edge-cases).
{% endhint %}

## Return value

| Returned              | Effect                                                             |
| --------------------- | ------------------------------------------------------------------ |
| `defaultTemplateName` | The configured template is sent.                                   |
| Another template name | That template is sent. It must be an email template of the tenant. |
| `null` or `undefined` | No email is sent.                                                  |

When no email is sent, the enrolment request still answers that a confirmation email was sent to the customer's address, since the challenge itself took place. A front end that relies on that answer then tells the customer to check an inbox that receives nothing, so skipping the email is reserved for cases where the customer is told otherwise.

## Errors and edge cases

* **GetEmailTemplate throws or its promise rejects**: no email is sent and the enrolment request fails.
* **GetEmailTemplate is missing** from the registered object: the challenge fails when the script is called.
* **No script registers the key**: the configured `templateName` is used.
* **Several files register the key**: the last registered wins, and the load order of files is not defined.

## Example

Customers already known to the CRM, recognized by the CRM identifier a customer provider found, receive a "welcome back" email. The others receive the configured email. The example needs `checkInSecurityMode: partial`, as explained in the pitfalls below.

```js
async function getEmailTemplate(data, defaultTemplateName) {
  if (data['id.crm.customerId']) {
    return 'confirm-identity-returning';
  }
  return defaultTemplateName;
}

export default function (context) {
  context.register('runtime.emailAccountChallenger.templateFinder', {
    GetEmailTemplate: getEmailTemplate
  });
}
```

A language variant picks the template from a language value of the account, with the default as fallback.

```js
const TEMPLATE_BY_LANGUAGE = { fr: 'confirm-identity-fr', nl: 'confirm-identity-nl' };

async function getEmailTemplate(data, defaultTemplateName) {
  const language = String(data['neo.lng'] ?? '').toLowerCase();
  return TEMPLATE_BY_LANGUAGE[language] ?? defaultTemplateName;
}
```

The prefix `neostore` is the platform's former name and is kept in technical identifiers such as `neo.lng`.

## Checking the result

A test enrolment with a mailbox the team controls shows which template arrived. Trying both cases (a known and an unknown customer) confirms each branch. When no email arrives at all, the platform's monitoring shows whether the script threw, and the email provider's logs whether a send was attempted.

## Common pitfalls

* The template returned by the script does not exist in the tenant's email templates.
* With `checkInSecurityMode: full`, the customer providers have not run when the email is sent, so a test on an identifier never matches; `partial` mode looks the customer up first.
* Returning `null` by mistake (a missing `return` in one branch of an `async` function) silently suppresses the email.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/developers-guides/scripting/endpoints/email-challenge-template.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
