Groundmail for AdonisJS

An AdonisJS mail transport for the Groundmail transactional email API.
Keep mail.send() and your mail classes; deliver through Groundmail.

Docs · Get a free account · groundmail.dev

---

Works with @adonisjs/mail 9 (AdonisJS 6) and 10 (AdonisJS 7).

Install

npm install adonisjs-groundmail

GROUNDMAIL_API_KEY=gm_your_key_here

Configure

// 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> {}
}

Add GROUNDMAIL_API_KEY: Env.schema.string() to start/env.ts.

Send

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 })
})

Attachments from message.attach(), attachData() and embed() are read and sent with the message. Queued mail (mail.sendLater) works the same way.

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

Contributing

Found a bug or want something added? Open an issue. This code is published here on each release, so we port fixes rather than merging pull requests directly. The HTTP client itself is the groundmail package.

Why Groundmail

• Mailboxes for your agents. Give an agent its own email address: it receives mail, replies in the thread and picks up sign-up codes on its own. No account needed to start. Agent mailboxes
• Each kind of mail on its own IPs. Transactional email (sign-in codes, password resets, receipts), product email and opt-in newsletters send from separate IPs, so your newsletter never shares a pool with your password resets. We run our own mail servers and never send cold outreach or bought lists.
• Start free. Free covers 3,000 emails a month. After that, pay as you go is $15 a month with 20,000 emails included, then from $0.70 per 1,000, less as you grow. Pricing
• Built for code and for agents. REST API, SMTP, SDKs for Node, Python, Go, PHP and Ruby, a CLI, and an MCP server for Claude, ChatGPT and Cursor.

All Groundmail libraries

Use	Package
Node.js / TypeScript	groundmail on npm
Python (Django), Go, Ruby (Rails Action Mailer)	Groundmail/groundmail-sdks
PHP	Groundmail/groundmail-php
Laravel	Groundmail/groundmail-laravel
Symfony Mailer	Groundmail/groundmail-symfony-mailer
Nodemailer	Groundmail/groundmail-nodemailer
NestJS	Groundmail/nestjs-groundmail
Strapi	Groundmail/strapi-provider-email-groundmail
Medusa	Groundmail/medusa-notification-groundmail
AdonisJS	Groundmail/adonisjs-groundmail
Phoenix (Swoosh)	Groundmail/swoosh_groundmail
CLI	groundmail-cli on npm
MCP server (Claude, ChatGPT, Cursor)	Groundmail/groundmail-mcp
Agent skills and Claude Code plugin	Groundmail/groundmail-skills
Email templates (React Email, MJML, HTML)	Groundmail/email-templates

Website · Docs · Pricing · Sign up free