邮件

node ace add @adonisjs/mail

# 通过 CLI 标志预定义要使用的传输方式
node ace add @adonisjs/mail --transports=resend --transports=smtp

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

const mailConfig = defineConfig({
  default: 'smtp',

  /**
   * “from” 属性的静态地址。除非在电子邮件上明确设置了 from 地址，
   * 否则将使用该地址。
   */
  from: {
    address: '',
    name: '',
  },

  /**
   * “reply-to” 属性的静态地址。除非在电子邮件上明确设置了 replyTo 地址，
   * 否则将使用该地址。
   */
  replyTo: {
    address: '',
    name: '',
  },

  /**
   * mailers 对象可用于配置多个邮件发送器，每个邮件发送器使用不同的传输方式或
   * 相同传输方式但选项不同。
   */
  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',
    }),
  },
})

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

export default class UsersController {
  async store({ request }: HttpContext) {
    /**
     * 仅用于演示。你应在将数据存储在数据库之前
     * 验证数据。
     */
    const user = await User.create(request.all())

    await mail.send((message) => {
      message
        .to(user.email)
        .from('info@example.org')
        .subject('Verify your email address')
        .htmlView('emails/verify_email', { user })
    })
  }
}

await mail.send((message) => {
await mail.sendLater((message) => {
  message
    .to(user.email)
    .from('info@example.org')
    .subject('Verify your email address')
    .htmlView('emails/verify_email', { 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) {
      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

    await mail
      .use(mailerName)
      .sendCompiled(mailMessage, config)
  }
})

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

mail.use() // 默认邮件发送器的实例
mail.use('mailgun') // Mailgun 邮件发送器实例

await mail
  .use('mailgun')
  .send((message) => {
  })

await mail
  .use('mailgun')
  .sendLater((message) => {
  })

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

/**
 * 关闭传输并从缓存中移除实例
 */
await mail.close('mailgun')

/**
 * 创建一个新的实例
 */
mail.use('mailgun')

import { Message } from '@adonisjs/mail'

Message.templateEngine = {
  async render(templatePath, data) {
    return someTemplateEngine.render(templatePath, data)
  }
}

import { Message } from '@adonisjs/mail'
import mail from '@adonisjs/mail/services/main'

await mail.send((message) => {
  console.log(message instanceof Message) // true
})

await mail.sendLater((message) => {
  console.log(message instanceof Message) // true
})

await mail.send((message) => {
  message
    .subject('验证你的电子邮件地址')
    .from('info@example.org')
})

message
  .from({
    address: 'info@example.com',
    name: 'AdonisJS'
  })

const mailConfig = defineConfig({
  from: {
    address: 'info@example.com',
    name: 'AdonisJS'
  }
})

await mail.send((message) => {
  message
    .to(user.email)
    .cc(user.team.email)
    .bcc(user.team.admin.email)
})

await mail.send((message) => {
  message
    .to({
      address: user.email,
      name: user.fullName,
    })
    .cc({
      address: user.team.email,
      name: user.team.name,
    })
    .bcc({
      address: user.team.admin.email,
      name: user.team.admin.fullName,
    })
})

await mail.send((message) => {
  message
    .cc(['first@example.com', 'second@example.com'])
    .bcc([
      {
        name: 'First recipient',
        address: 'first@example.com'
      },
      {
        name: 'Second recipient',
        address: 'second@example.com'
      }
    ])
})

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

await mail.send((message) => {
  /**
   * HTML 内容
   */
  message.html(`
    <h1> 验证电子邮件地址 </h1>
    <p> <a href="https://myapp.com">点击这里</a> 以验证你的电子邮件地址 </a>
  `)

  /**
   * 纯文本内容
   */
  message.text(`
    验证电子邮件地址
    请访问 https://myapp.com 以验证你的电子邮件地址
  `)
})

node ace make:view emails/verify_email_html
node ace make:view emails/verify_email_text

await mail.send((message) => {
  message.htmlView('emails/verify_email_html', stateToShare)
  message.textView('emails/verify_email_text', stateToShare)
})

npm i mjml

@mjml()
  <mjml>
    <mj-body>
      <mj-section>
        <mj-column>
          <mj-text>
            Hello World!
          </mj-text>
        </mj-column>
      </mj-section>
    </mj-body>
  </mjml>
@end

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

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

await mail.send((message) => {
  message.attach(app.makePath('uploads/invoice.pdf'))
})

message.attach(app.makePath('uploads/invoice.pdf'), {
  filename: 'invoice_october_2023.pdf'
})

message.attachData(fs.createReadStream('./invoice.pdf'), {
  filename: 'invoice_october_2023.pdf'
})

message.attachData(Buffer.from('aGVsbG8gd29ybGQh'), {
  encoding: 'base64',
  filename: 'greeting.txt',
})

<img src="{{
  embedImage(app.makePath('assets/hero.jpg'))
}}" />

<img src="cid:a-random-content-id" />

{
  attachments: [{
    path: '/root/app/assets/hero.jpg',
    filename: 'hero.jpg',
    cid: 'a-random-content-id'
  }]
}

<img src="{{
  embedImageData(rawBuffer, { filename: 'hero.jpg' })
}}" />

const contents = 'BEGIN:VCALENDAR\r\nPRODID:-//ACME/DesktopCalendar//EN\r\nMETHOD:REQUEST\r\n...'

await mail.send((message) => {
  message.icalEvent(contents, {
    method: 'PUBLISH',
    filename: 'invite.ics',
  })
})

message.icalEvent((calendar) => {
  calendar
    .createEvent({
      summary: 'Adding support for ALS',
      start: DateTime.local().plus({ minutes: 30 }),
      end: DateTime.local().plus({ minutes: 60 }),
    })
}, {
  method: 'PUBLISH',
  filename: 'invite.ics',
})

message.icalEventFromFile(
  app.resourcesPath('calendar-invites/invite.ics'),
  {
    filename: 'invite.ics',
    method: 'PUBLISH'
  }
)

message.icalEventFromFile(
  'https://myapp.com/users/1/invite.ics',
  {
    filename: 'invite.ics',
    method: 'PUBLISH'
  }
)

message.header('x-my-key', 'header value')

/**
 * 定义值数组
 */
message.header('x-my-key', ['header value', 'another value'])

message.preparedHeader(
  'x-unprocessed',
  'a really long header or value with non-ascii characters 👮',
)

message.listHelp('admin@example.com?subject=help')
// List-Help: <mailto:admin@example.com?subject=help>

message.listUnsubscribe({
  url: 'http://example.com',
  comment: 'Comment'
})
// List-Unsubscribe: <http://example.com> (Comment)

/**
 * 多次重复头
 */
message.listSubscribe('admin@example.com?subject=subscribe')
message.listSubscribe({
  url: 'http://example.com',
  comment: 'Subscribe'
})
// List-Subscribe: <mailto:admin@example.com?subject=subscribe>
// List-Subscribe: <http://example.com> (Subscribe)

message.addListHeader('post', 'http://example.com/post')
// List-Post: <http://example.com/post>

node ace make:mail verify_email

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

export default class VerifyEmailNotification extends BaseMail {
  from = 'sender_email@example.org'
  subject = 'Verify email'

  prepare() {
    this.message.to('user_email@example.org')
  }
}

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

await mail.send(new VerifyEmailNotification())

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

await mail.sendLater(new VerifyEmailNotification())

/**
 * 创建用户
 */
const user = await User.create(payload)

await mail.send(
  /**
   * 将用户传递给 mail 类
   */
  new VerifyEmailNotification(user)
)

import { test } from '@japa/runner'
import VerifyEmailNotification from '#mails/verify_email'

test.group('验证电子邮件通知', () => {
  test('准备发送的电子邮件', async () => {
    const email = new VerifyEmailNotification()

    /**
     * 构建电子邮件消息并渲染模板以
     * 计算电子邮件的 HTML 和纯文本
     * 内容
     */
    await email.buildWithContents()

    /**
     * 编写断言以确保消息按预期构建
     */
    email.message.assertTo('user@example.org')
    email.message.assertFrom('info@example.org')
    email.message.assertSubject('验证电子邮件地址')
    email.message.assertReplyTo('no-reply@example.org')
  })
})

const email = new VerifyEmailNotification()
await email.buildWithContents()

email.message.assertHtmlIncludes(
  `<a href="/emails/1/verify"> 验证电子邮件地址 </a>`
)
email.message.assertTextIncludes('验证电子邮件地址')

const email = new VerifyEmailNotification()
await email.buildWithContents()

email.message.assertAttachment(
  app.makePath('uploads/invoice.pdf')
)

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

test.group('用户 | 注册', () => {
  test('创建新的用户帐户', async ({ client, route }) => {
    /**
     * 开启虚拟模式
     */
    const { mails } = mail.fake()

    /**
     * 发起 API 调用
     */
    await client
      .post(route('users.store'))
      .send(userData)

    /**
     * 断言控制器确实发送了
     * VerifyEmailNotification 邮件
     */
    mails.assertSent(VerifyEmailNotification, ({ message }) => {
      return message
        .hasTo(userData.email)
        .hasSubject('验证电子邮件地址')
    })
  })
})

test('创建新的用户帐户', async ({ client, route, cleanup }) => {
  const { mails } = mail.fake()

  /**
   * 清理钩子在测试成功完成或出错后执行。
   */
  cleanup(() => {
    mail.restore()
  })
})

const { mails } = mail.fake()

/**
 * 断言已发送电子邮件
 */
mails.assertSent(VerifyEmailNotification)

mails.assertSent(VerifyEmailNotification, (email) => {
  return email.message.hasTo(userData.email)
})

mails.assertSent(VerifyEmailNotification, (email) => {
  email.message.assertTo(userData.email)
  email.message.assertFrom('info@example.org')
  email.message.assertSubject('验证你的电子邮件地址')

  /**
   * 所有断言均通过，因此返回 true 以认为
   * 电子邮件已发送。
   */
  return true
})

const { mails } = mail.fake()

mails.assertNotSent(PasswordResetNotification)

const { mails } = mail.fake()

// Assert 2 emails were sent in total
mails.assertSentCount(2)

// 断言仅发送了一封 VerifyEmailNotification 邮件
mails.assertSentCount(VerifyEmailNotification, 1)

const { mails } = mail.fake()

// 断言未发送任何邮件
mails.assertNoneSent()

const { mails } = mail.fake()

/**
 * 断言 "VerifyEmailNotification" 邮件已排入队列
 * 可选地，你可以传递查找函数以缩小邮件范围
 */
mails.assertQueued(VerifyEmailNotification)

/**
 * 断言 "VerifyEmailNotification" 邮件未排入队列
 * 可选地，你可以传递查找函数以缩小邮件范围
 */
mails.assertNotQueued(PasswordResetNotification)

/**
 * 断言总共排入了两封邮件。
 */
mails.assertQueuedCount(2)

/**
 * 断言 "VerifyEmailNotification" 邮件仅排入了一次
 */
mails.assertQueuedCount(VerifyEmailNotification, 1)

/**
 * 断言未排入任何邮件
 */
mails.assertNoneQueued()

const { mails } = mail.fake()

const sentEmails = mails.sent()
const queuedEmails = mails.queued()

const email = sentEmails.find((email) => {
  return email instanceof VerifyEmailNotification
})

if (email) {
  email.message.assertTo(userData.email)
  email.message.assertFrom(userData.email)
  email.message.assertHtmlIncludes('<a href="/verify/email"> Verify your email address</a>')
}

npm i nodemailer nodemailer-postmark-transport

import nodemailer from 'nodemailer'
import nodemailerTransport from 'nodemailer-postmark-transport'

import { MailResponse } from '@adonisjs/mail'
import type {
  NodeMailerMessage,
  MailTransportContract
} from '@adonisjs/mail/types'

/**
 * 传输接受的配置
 */
export type PostMarkConfig = {
  auth: {
    apiKey: string
  }
}

/**
 * 传输实现
 */
export class PostMarkTransport implements MailTransportContract {
  #config: PostMarkConfig
  constructor(config: PostMarkConfig) {
    this.#config = config
  }

  #createNodemailerTransport(config: PostMarkConfig) {
    return nodemailer.createTransport(nodemailerTransport(config))
  }

  async send(
    message: NodeMailerMessage,
    config?: PostMarkConfig
  ): Promise<MailResponse> {
    /**
     * 创建 nodemailer 传输
     */
    const transporter = this.#createNodemailerTransport({
      ...this.#config,
      ...config,
    })

    /**
     * 发送邮件
     */
    const response = await transporter.sendMail(message)

    /**
     * 将响应规范化为 "MailResponse" 类的实例
     */
    return new MailResponse(response.messageId, response.envelope, response)
  }
}

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

export function postMarkTransport(
  config: PostMarkConfig
): MailManagerTransportFactory {
  return () => {
    return new PostMarkTransport(config)
  }
}

import env from '#start/env'
import { defineConfig } from '@adonisjs/mail'
import { postMarkTransport } from 'my-custom-package'

const mailConfig = defineConfig({
  mailers: {
    postmark: postMarkTransport({
      auth: {
        apiKey: env.get('POSTMARK_API_KEY'),
      },
    }),
  },
})