Groundmail with AdonisJS

Use adonisjs-groundmail as a mail transport for @adonisjs/mail. Your mail classes and mail.send() calls stay the same; delivery goes through the Groundmail HTTP API. It works with @adonisjs/mail 9 (AdonisJS 6) and 10 (AdonisJS 7).

1. Install

npm install adonisjs-groundmail

GROUNDMAIL_API_KEY=gm_your_key_here

Add the key to start/env.ts:

GROUNDMAIL_API_KEY: Env.schema.string(),

2. Add the mailer

// config/mail.ts
import env from '#start/env'
import { defineConfig } from '@adonisjs/mail'
import { groundmailTransport } from 'adonisjs-groundmail'

const mailConfig = defineConfig({
  default: 'groundmail',
  mailers: {
    groundmail: groundmailTransport({
      apiKey: env.get('GROUNDMAIL_API_KEY'),
    }),
  },
})

export default mailConfig

declare module '@adonisjs/mail/types' {
  export interface MailersList extends InferMailers<typeof mailConfig> {}
}

3. Send an email

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

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

The From address must be on a domain you have verified in Groundmail. Attachments from message.attach(), attachData() and embed() are read and sent with the message, and queued mail (mail.sendLater) uses the same transport.

Groundmail headers

message.header('X-Groundmail-Tag', 'flow=signup')
message.header('X-Groundmail-Idempotency-Key', `verify-${user.id}`)

Header	Purpose
`X-Groundmail-Tag`	`name=value` tag (repeatable)
`X-Groundmail-Idempotency-Key`	Send once, even when your code retries
`X-Groundmail-Scheduled-At`	ISO 8601 time to send later

Source

Groundmail/adonisjs-groundmail