EmailSender extensibility

Implement a script-based email provider by registering `runtime.scriptable.emailEngine.SendEmail`.

What this is

Use this extensibility point when you want The Wallet Crew to send emails through a provider you control. This is a script-level integration. It lets you keep Wallet Crew templates and rendering logic, while delegating the final “send” to your own API calls.

This design separates rendering from delivery. That makes your email layer easier to test and easier to swap. It also keeps culture handling explicit, because the caller decides which cultures exist and how templates are resolved.

How SendEmail works

The platform calls runtime.scriptable.emailEngine.SendEmail when it needs to send an email and the email provider is set to script. The function receives the recipient address, the template name, a data payload, and the list of supported cultures.

The last parameter, buildEmail, is a callback supplied by the platform. Your provider calls it to obtain the final rendered content. That callback returns an object with a Subject and a Body. Once you have that payload, your script is responsible for sending it.

Reference implementation (signature)

/**
 * @typedef {Object} EmailData
 * @property {string} Subject - Rendered subject line.
 * @property {string} Body - Rendered body content.
 */

/**
 * Send an email using the provided template name and data.
 * The caller supplies the supported cultures and a callback
 * to build the rendered email content.
 *
 * @param {string} recipient - Target email address.
 * @param {string} emailTemplate - Template name to render.
 * @param {Object.<string, any>} data - Template data passed to the script.
 * @param {string[]} cultures - Available culture names from the culture provider.
 * @param {(templateName: string) => Promise<EmailData>} buildEmail
 * Callback that returns the final rendered email content.
 *
 * @returns {Promise<void>}
 */
async function sendEmail(recipient, emailTemplate, data, cultures, buildEmail){
   // call any API to send email
}

export default function(context) {
  context.register('runtime.scriptable.emailEngine', {
    SendEmail: sendEmail 
  })
}

Enable the script email provider

Switching to the script email provider is a configuration change. It tells The Wallet Crew to call your SendEmail implementation for outgoing emails.

1

Edit /server/emails.yml

Open the advanced configuration editor, then create or edit /server/emails.yml. Set the provider type to script. Keep resources pointing to your email template directory.

provider:
  type: script
resources:
  - /locales/emails/

Template and culture notes

Email templates are loaded from the paths listed under resources. Keep this aligned with where your HTML templates live, because the rendering callback uses those templates.

Culture handling is part of the contract. The platform passes a cultures array, but your provider decides how to use it. In practice, most setups either pick a single culture per recipient or fall back to a default culture when no specific template exists.

Troubleshooting

If emails stop sending after enabling the script provider, start by confirming that /server/emails.yml is valid YAML and saved in the right tenant. Then confirm your script is actually registered under runtime.scriptable.emailEngine and exports SendEmail.

If you see provider-side errors, log the template name and culture choices, but avoid logging full rendered bodies. Email content can contain personal data.

FAQ

Is this a public HTTP endpoint?

No. This page documents a script runtime interface that your tenant script implements. If you want to call an external HTTP API, you do it from inside SendEmail.

Where do email templates live?

They live under the directories listed in resources. By default, this points to /locales/emails/.

Can we mix a script provider with SendGrid or Mailchimp?

Not at the same time for a given tenant. The active provider is selected in /server/emails.yml.

What should we return from SendEmail?

Return normally when the email is accepted by your provider. Throw an error when sending fails, so the platform can surface it.

What’s the fastest way to validate the setup?

Enable the script provider, trigger a single transactional email, then check your provider logs for the send event.