邮件

node ace add @adonisjs/mail

node ace add @adonisjs/mail --transports=resend --transports=smtp

import env from '#start/env'
import { defineConfig, transports } from '@adonisjs/mail'

const mailConfig = defineConfig({
  /**
   * 未指定 mailer 时使用的 mailer
   */
  default: 'smtp',

  /**
   * 未在各封邮件上设置时使用的全局「from」地址
   */
  from: {
    address: 'hello@example.com',
    name: 'My App',
  },

  /**
   * 未在各封邮件上设置时使用的全局「reply-to」地址
   */
  replyTo: {
    address: 'support@example.com',
    name: 'My App Support',
  },

  /**
   * 配置一个或多个 mailer。每个 mailer 使用一种传输方式，
   * 并可以有自己的设置。
   */
  mailers: {
    smtp: transports.smtp({
      host: env.get('SMTP_HOST'),
      port: env.get('SMTP_PORT'),
    }),

    resend: transports.resend({
      key: env.get('RESEND_API_KEY'),
      baseUrl: 'https://api.resend.com',
    }),
  },
})

export default mailConfig

import type { HttpContext } from '@adonisjs/core/http'
import mail from '@adonisjs/mail/services/main'
import User from '#models/user'

export default class UsersController {
  async store({ request }: HttpContext) {
    const user = await User.create(request.all())

    /**
     * 创建用户后发送一封欢迎邮件。
     * 回调负责配置邮件属性。
     */
    await mail.send((message) => {
      message
        .to(user.email)
        .from('welcome@example.com')
        .subject('Welcome to our app!')
        .htmlView('emails/welcome', { user })
    })

    return user
  }
}

await mail.send((message) => {
  message
    .subject('Your order has shipped')
    .from('orders@example.com')
})

await mail.send((message) => {
  message.from({
    address: 'orders@example.com',
    name: 'Acme Store'
  })
})

await mail.send((message) => {
  message
    .to(user.email)
    .cc(user.manager.email)
    .bcc('audit@example.com')
})

await mail.send((message) => {
  message
    .to({
      address: user.email,
      name: user.fullName,
    })
    .cc([
      { address: 'team-lead@example.com', name: 'Team Lead' },
      { address: 'pm@example.com', name: 'Project Manager' }
    ])
})

await mail.send((message) => {
  message
    .from('noreply@example.com')
    .replyTo('support@example.com')
})

await mail.send((message) => {
  /**
   * 内联内容适用于简单邮件
   */
  message.html(`
    <h1>Reset your password</h1>
    <p>Click <a href="${resetUrl}">here</a> to reset your password.</p>
  `)

  message.text(`
    Reset your password
    Visit ${resetUrl} to reset your password.
  `)
})

node ace make:view emails/password_reset_html
node ace make:view emails/password_reset_text

await mail.send((message) => {
  /**
   * 渲染 Edge 模板，将数据作为第二个参数传入
   */
  message.htmlView('emails/password_reset_html', { user, resetUrl })
  message.textView('emails/password_reset_text', { user, resetUrl })
})

npm i mjml

@mjml()
  <mjml>
    <mj-body>
      <mj-section>
        <mj-column>
          <mj-text font-size="20px" color="#333">
            Welcome, {{ user.name }}!
          </mj-text>
          <mj-button href="{{ verifyUrl }}">
            Verify Email
          </mj-button>
        </mj-column>
      </mj-section>
    </mj-body>
  </mjml>
@end

@mjml({
  keepComments: false,
  fonts: {
    Lato: 'https://fonts.googleapis.com/css?family=Lato:400,500,700'
  }
})
  {{-- MJML 内容 --}}
@end

import mail from '@adonisjs/mail/services/main'

export default class UsersController {
  async store({ request }: HttpContext) {
    const user = await User.create(request.all())

    /**
     * 将邮件加入队列，而非立即发送。
     * 请求无需等待投递即可完成。
     */
    await mail.sendLater((message) => {
      message
        .to(user.email)
        .from('welcome@example.com')
        .subject('Welcome!')
        .htmlView('emails/welcome', { user })
    })

    return user
  }
}

npm i bullmq

import { Queue } from 'bullmq'
import mail from '@adonisjs/mail/services/main'

const emailsQueue = new Queue('emails')

mail.setMessenger((mailer) => {
  return {
    async queue(mailMessage, config) {
      /**
       * 存储已编译的消息、配置和 mailer 名称。
       * 一个 worker 进程会取走它并发送。
       */
      await emailsQueue.add('send_email', {
        mailMessage,
        config,
        mailerName: mailer.name,
      })
    }
  }
})

import { Worker } from 'bullmq'
import mail from '@adonisjs/mail/services/main'

new Worker('emails', async (job) => {
  if (job.name === 'send_email') {
    const { mailMessage, config, mailerName } = job.data

    /**
     * 使用指定的 mailer 发送预编译的消息
     */
    await mail.use(mailerName).sendCompiled(mailMessage, config)
  }
})

import mail from '@adonisjs/mail/services/main'

/**
 * 通过默认 mailer 发送事务性邮件
 */
await mail.send((message) => {
  message.subject('Order confirmed')
})

/**
 * 通过 Mailgun 发送营销邮件
 */
await mail.use('mailgun').send((message) => {
  message.subject('Weekly newsletter')
})

/**
 * 通过特定 mailer 将邮件加入队列
 */
await mail.use('resend').sendLater((message) => {
  message.subject('Your report is ready')
})

import mail from '@adonisjs/mail/services/main'

/**
 * 关闭 mailgun 连接并从缓存中移除
 */
await mail.close('mailgun')

/**
 * 下一次调用会创建全新的实例
 */
mail.use('mailgun')

import app from '@adonisjs/core/services/app'

await mail.send((message) => {
  message.attach(app.makePath('storage/invoices/inv-001.pdf'))
})

await mail.send((message) => {
  message.attach(app.makePath('storage/invoices/inv-001.pdf'), {
    filename: 'invoice-october-2024.pdf',
    contentType: 'application/pdf',
  })
})

import fs from 'node:fs'

await mail.send((message) => {
  /**
   * 从可读流附加
   */
  message.attachData(fs.createReadStream('./report.pdf'), {
    filename: 'report.pdf'
  })

  /**
   * 从缓冲区附加
   */
  message.attachData(Buffer.from('Hello world'), {
    filename: 'greeting.txt',
    encoding: 'utf-8',
  })
})

<img src="{{ embedImage(app.makePath('assets/logo.png')) }}" alt="Logo" />

<img src="{{ embedImageData(chartBuffer, { filename: 'chart.png' }) }}" />

import { DateTime } from 'luxon'

await mail.send((message) => {
  message.icalEvent((calendar) => {
    calendar.createEvent({
      summary: 'Project kickoff meeting',
      start: DateTime.now().plus({ days: 1 }).set({ hour: 10 }),
      end: DateTime.now().plus({ days: 1 }).set({ hour: 11 }),
      location: 'Conference Room A',
    })
  }, {
    method: 'REQUEST',
    filename: 'meeting.ics',
  })
})

import app from '@adonisjs/core/services/app'

await mail.send((message) => {
  /**
   * 来自本地文件
   */
  message.icalEventFromFile(
    app.resourcesPath('invites/standup.ics'),
    { method: 'REQUEST', filename: 'standup.ics' }
  )

  /**
   * 来自 URL
   */
  message.icalEventFromUrl(
    'https://example.com/calendar/event-123.ics',
    { method: 'REQUEST', filename: 'event.ics' }
  )
})

await mail.send((message) => {
  message.header('X-Entity-Ref', 'order-12345')
  message.header('X-Priority', '1')
})

await mail.send((message) => {
  message.preparedHeader(
    'X-Custom-Data',
    'value with special chars or very long content'
  )
})

await mail.send((message) => {
  message.listUnsubscribe({
    url: 'https://example.com/unsubscribe?token=abc',
    comment: 'Unsubscribe from this list'
  })

  message.listHelp('support@example.com?subject=help')

  /**
   * 对于其他 List-* 请求头
   */
  message.addListHeader('post', 'https://example.com/list/post')
})

await mail.send((message) => {
  message.listUnsubscribe('https://example.com/unsubscribe?token=abc', {
    oneClick: true
  })
})

node ace make:mail verify_email

import User from '#models/user'
import router from '@adonisjs/core/services/router'
import { BaseMail } from '@adonisjs/mail'

export default class VerifyEmailNotification extends BaseMail {
  /**
   * 为常见邮件选项设置类属性
   */
  from = 'noreply@example.com'
  subject = 'Please verify your email address'

  constructor(private user: User) {
    super()
  }

  /**
   * 在 prepare 方法中配置邮件。
   * 会在发送前自动调用。
   */
  prepare() {
    const verifyUrl = router.makeUrl('email.verify', {
      token: this.user.verificationToken
    })

    this.message
      .to(this.user.email)
      .htmlView('emails/verify_email', {
        user: this.user,
        verifyUrl,
      })
  }
}

import mail from '@adonisjs/mail/services/main'
import VerifyEmailNotification from '#mails/verify_email'

export default class AuthController {
  async register({ request }: HttpContext) {
    const user = await User.create(request.all())

    await mail.sendLater(new VerifyEmailNotification(user))

    return { message: 'Check your email to verify your account' }
  }
}

import { test } from '@japa/runner'
import mail from '@adonisjs/mail/services/main'
import VerifyEmailNotification from '#mails/verify_email'

test.group('Users | register', () => {
  test('sends verification email on registration', async ({ client }) => {
    /**
     * Fake 该 mailer。`using` 关键字会在测试结束时
     * 自动恢复真实的 mailer。
     */
    using fake = mail.fake()

    await client
      .post('/register')
      .form({ email: 'user@example.com', password: 'secret123' })

    /**
     * 断言邮件已被发送
     */
    fake.mails.assertSent(VerifyEmailNotification, ({ message }) => {
      return message
        .hasTo('user@example.com')
        .hasSubject('Please verify your email address')
    })
  })

  test('does not send password reset when user not found', async ({ client }) => {
    using fake = mail.fake()

    await client
      .post('/forgot-password')
      .form({ email: 'unknown@example.com' })

    fake.mails.assertNotSent(PasswordResetNotification)
  })
})

import { test } from '@japa/runner'
import { UserFactory } from '#database/factories/user_factory'
import VerifyEmailNotification from '#mails/verify_email'

test.group('VerifyEmailNotification', () => {
  test('builds correct message', async () => {
    const user = await UserFactory.create()
    const email = new VerifyEmailNotification(user)

    /**
     * 构建邮件并渲染模板
     */
    await email.buildWithContents()

    /**
     * 断言邮件属性
     */
    email.message.assertTo(user.email)
    email.message.assertFrom('noreply@example.com')
    email.message.assertSubject('Please verify your email address')

    /**
     * 断言渲染后的内容
     */
    email.message.assertHtmlIncludes(`Hello ${user.name}`)
    email.message.assertHtmlIncludes('/verify/')
  })
})

using fake = mail.fake()

/**
 * 获取所有已发送的邮件
 */
const sentEmails = fake.mails.sent()

/**
 * 获取所有已加入队列的邮件
 */
const queuedEmails = fake.mails.queued()

/**
 * 查找特定的邮件
 */
const verifyEmail = sentEmails.find((email) => {
  return email instanceof VerifyEmailNotification
})

if (verifyEmail) {
  verifyEmail.message.assertHtmlIncludes('Verify your email')
}

import nodemailer from 'nodemailer'
import mandrillTransport from 'nodemailer-mandrill-transport'
import { MailResponse } from '@adonisjs/mail'
import type { NodeMailerMessage, MailTransportContract } from '@adonisjs/mail/types'

export type MandrillConfig = {
  auth: {
    apiKey: string
  }
}

export class MandrillTransport implements MailTransportContract {
  #config: MandrillConfig

  constructor(config: MandrillConfig) {
    this.#config = config
  }

  async send(
    message: NodeMailerMessage,
    config?: MandrillConfig
  ): Promise<MailResponse> {
    /**
     * 使用合并后的配置创建 nodemailer 传输
     */
    const transporter = nodemailer.createTransport(
      mandrillTransport({ ...this.#config, ...config })
    )

    const response = await transporter.sendMail(message)

    /**
     * 返回归一化后的响应
     */
    return new MailResponse(response.messageId, response.envelope, response)
  }
}

import type { MailManagerTransportFactory } from '@adonisjs/mail/types'

export function mandrillTransport(
  config: MandrillConfig
): MailManagerTransportFactory {
  return () => new MandrillTransport(config)
}

import env from '#start/env'
import { defineConfig } from '@adonisjs/mail'
import { mandrillTransport } from '#app/mail/transports/mandrill'

const mailConfig = defineConfig({
  mailers: {
    mandrill: mandrillTransport({
      auth: {
        apiKey: env.get('MANDRILL_API_KEY'),
      },
    }),
  },
})

import { Message } from '@adonisjs/mail'

Message.templateEngine = {
  async render(templatePath, data) {
    /**
     * 使用你偏好的模板引擎
     */
    return myTemplateEngine.render(templatePath, data)
  }
}