add-mailer

Add a mailer

Emails are EJS templates under a feature's mailers/ folder, sent via the global services/email.js. Read README "Mailers".

Steps

1. Plan/sign-off: define recipient policy, trigger, template inputs, failure behavior, and tests; get sign-off before scaffolding or edits. Preview/apply complete structure with yarn repair <Feature> --dry-run then yarn repair <Feature>.

2. Scaffold: yarn gen <Feature> -m <MailerName>. This validates PascalCase names/targets, creates the mailer folder, and exclusively creates index.ejs; an existing folder/template aborts before any write. The feature name is prepended only if absent. Never hand-create.

3. Write index.ejs:

   • Top comment listing the args (template variables) the email expects.
   • Reference every variable as locals.<var> with a default fallback (e.g. <%= locals.firstName || 'there' %>) — required so the gulpfile can generate preview.html without erroring.
   • Always include the test-email banner driven by locals.isTestEmail (so non-prod emails are visibly marked).

4. Preview: run yarn gulp (watches index.ejs and regenerates preview.html). You won't see a preview.html until the gulpfile runs.

5. Send it from an action or task via services/email.js:

   const email = require('../../../services/email');
   await email.send({
     from: email.emails.<sender>.address,
     name: email.emails.<sender>.name,
     subject: '...',
     template: '<Feature><MailerName>', // = the mailer folder name
     tos: [recipientEmail],
     ccs: null, bccs: null,
     args: { firstName, ... } // the template variables
   });
   

   • Sending email is usually best done in a background task (enqueue from the action), not inline in the request — see the add-task skill.

6. Tests/checks: assert the email service was called (jest.spyOn(email, 'send')) with the right template + args; in task tests assert the send happened as a side effect. Run yarn conventions:check, focused tests, then yarn test; finish with mandatory review-conventions.