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('[email protected]')
    .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

• Our own mail servers and IP space. Your password resets and receipts don't share a pool with bulk marketing senders.
• Transactional email only. No newsletters or cold outreach on the platform, which keeps the sending reputation clean.
• Start free. 3,000 emails a month on the Free plan; Pro is 50,000 emails for $20/month. Dedicated IPs on Scale.
• 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