@amsom-habitat/nest-mail

Client de l'API Mail interne et son module Nest, pendant du connecteur PHP amsom-habitat/mailer-sender. Le client ne fabrique pas les mails : il transmet une description à l'API, qui rend le template, envoie, journalise et redirige hors production. Les appels passent par @amsom-habitat/nest-http-client (à installer aussi).

code ──send({...})──▶ nest-mail ──POST /v2/send (JSON + X-API-Key)──▶ API Mail ──▶ SMTP

Nest

@Module({ imports: [MailModule.forRoot()] })   // tout vient de l'env

@Module({
  imports: [
    MailModule.forRootAsync({
      isGlobal: true,
      imports: [ConfigModule],
      inject: [ConfigService],
      useFactory: (config: ConfigService) => ({ baseUrl: config.get('URL_MAIL_OFFICE') }),
    }),
  ],
})

Envoyer — send()

Une seule méthode, un objet ; ajouter une option = ajouter une clé.

constructor(private readonly mail: MailService) {}

const res = await this.mail.send({
  template: 'invit_hesta',          // omis → 'default' (template HTML tout-configurable)
  to: '[email protected]',       // ou un tableau d'adresses
  subject: 'Invitation',
  body: { numDemande: 'D-12' },
})
if (!res.success) throw new JsonErrorException(res.error ?? "Échec de l'envoi", 500)

POST <API_MAIL_URL>/v2/send, clé dans X-API-Key. Champs : template, to, subject, body, text, from (expéditeur réel, via le relay), replyTo, cc, cci, destinataire, attachments ([{ filename, content: base64 }]), options (logo, signature, auteur…), delivery. Le mail part tel quel : la redirection hors production est faite par l'API Mail.

Rend { success, httpStatus, id?, error? } : success si l'API répond 200 ou 202, sans lever sinon.

Options

| Option | Défaut | Rôle | |---|---|---| | baseUrl | API_MAIL_URL | URL de l'API Mail, sans /v2 (obligatoire, vérifiée au démarrage) | | apiKey | API_MAIL_KEY | clé de /v2/send, exigée au premier send | | timeoutMs | 30000 | délai maximal d'un appel | | isProduction | MAIL_ENV === 'prod' | routes historiques : hors production, garde-fou actif | | devRecipient | MAIL_DEV_RECIPIENT | routes historiques : destinataire unique hors production | | defaultLogo | MAIL_DEFAULT_LOGO, sinon null | apiSendMailCustom : logo quand templateConfig.logo est absent |

Erreurs

• send : une réponse en erreur rend success: false avec son statut et son corps décodé.
• API Mail injoignable ou délai dépassé : MailService lève une InternalServerErrorException (500), MailerSender une HttpClientError.

Routes historiques (dépréciées)

apiSendMail(route, params) poste sur {baseUrl}/{route} et apiSendMailCustom(params) sur {baseUrl}/send_custom, sans authentification, avec les noms de champs de l'ancienne API (emailDestinataire, sujet, attachement…). Hors production, le destinataire est remplacé par MAIL_DEV_RECIPIENT (exigé à l'appel) et cc / cci sont mis à null. La réponse est rendue décodée quel que soit son statut : c'est à l'appelant de tester result.data / result.error.

Node, sans Nest

import { MailerSender } from '@amsom-habitat/nest-mail'

const mailer = new MailerSender({ baseUrl: 'http://api_mail', apiKey: process.env.API_MAIL_KEY, logger: console })
await mailer.send({ to: '[email protected]', subject: 'Prélèvement', template: 'prelevement_auto' })

Migration

| 2.x | 3.0 | |---|---| | send(template, params) | apiSendMail(route, params) (déprécié) — ou send({ template, to, subject, body }) | | sendCustom(params) | apiSendMailCustom(params) (déprécié) — ou send({ template: 'custom', … }) | | MAIL_DEV_RECIPIENT exigé au démarrage hors prod | exigé à l'appel d'une route historique |

| 1.x | 2.0 | |---|---| | imports: [MailModule] | imports: [MailModule.forRoot()] | | MailModule.forRoot({ urlApiMail, environnement, destinataireDev }) | MailModule.forRoot({ baseUrl, isProduction, devRecipient }) | | MailerModule.forRoot(…) / forRootAsync(…), mailerModule() | MailModule.forRoot(…) / forRootAsync(…) | | new MailerSender({ baseUrl, env }) | new MailerSender({ baseUrl, isProduction }) | | repli [email protected] | MAIL_DEV_RECIPIENT | | logo logoAmsomEtMoi en dur | MAIL_DEFAULT_LOGO | | non-2xx → HttpClientError / exception du statut amont | corps décodé rendu, statut journalisé | | injoignable → 503 | 500 | | HttpClientError, httpClientErrorToHttpException | @amsom-habitat/nest-http-client | | MAILER_MODULE_OPTIONS, mapError | supprimés |