groundmailpb

README

Groundmail for PocketBase

Send PocketBase email through the Groundmail transactional email API instead of SMTP.
Verification emails, password resets, OTPs and your own sends all go through Groundmail.

Docs · Get a free account · groundmail.dev

---

For PocketBase used as a Go framework (v0.23 and later).

Install

go get github.com/Groundmail/groundmail-pocketbase

GROUNDMAIL_API_KEY=gm_your_key_here

Usage

package main

import (
	"log"

	groundmailpb "github.com/Groundmail/groundmail-pocketbase"
	"github.com/pocketbase/pocketbase"
)

func main() {
	app := pocketbase.New()

	// Reads GROUNDMAIL_API_KEY; or pass groundmailpb.Options{APIKey: "gm_…"}.
	if err := groundmailpb.Register(app, groundmailpb.Options{}); err != nil {
		log.Fatal(err)
	}

	if err := app.Start(); err != nil {
		log.Fatal(err)
	}
}

Register hooks OnMailerSend, so every email the app sends goes through Groundmail and PocketBase's SMTP settings are not used. Set the sender under Settings → Mail settings in the dashboard, on a domain you have verified in Groundmail.

Use the mailer directly

groundmailpb.Mailer implements PocketBase's mailer.Mailer interface:

m, err := groundmailpb.New(groundmailpb.Options{})
if err != nil {
	return err
}
return m.Send(&mailer.Message{
	From:    mail.Address{Name: "Acme", Address: "noreply@yourdomain.com"},
	To:      []mail.Address{{Address: "user@example.com"}},
	Subject: "Your receipt",
	HTML:    "<p>Thanks for your purchase.</p>",
})

Attachments and inline attachments are sent with the message; inline files are referenced by name (cid:logo.png).

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.

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, Go, Ruby	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
Rails (Action Mailer)	Groundmail/groundmail-rails
Phoenix (Swoosh)	Groundmail/swoosh_groundmail
PocketBase	Groundmail/groundmail-pocketbase
CLI	groundmail-cli on npm
MCP server (Claude, ChatGPT, Cursor)	Groundmail/groundmail-mcp
Agent skills and Claude Code plugin	Groundmail/groundmail-skills

Website · Docs · Pricing · Sign up free

Documentation

Overview

Package groundmailpb sends PocketBase emails through the Groundmail transactional email API instead of SMTP.

app := pocketbase.New()
if err := groundmailpb.Register(app, groundmailpb.Options{}); err != nil {
	log.Fatal(err)
}

Register binds the app's OnMailerSend hook, so password resets, email verification, OTPs and every app.NewMailClient().Send call go through Groundmail. Mailer also implements PocketBase's mailer.Mailer interface for direct use.

Index

• Constants
• func Register(app core.App, opts Options) error
• func SendParams(message *mailer.Message) (map[string]any, error)
• type Mailer
  • func New(opts Options) (*Mailer, error)
  • func (m *Mailer) Send(message *mailer.Message) error
• type Options

Constants

const Version = "0.1.0"

Version is the release of this module, tagged as v<Version> in github.com/Groundmail/groundmail-pocketbase.

Functions

func Register

func Register(app core.App, opts Options) error

Register routes every email the app sends through Groundmail.

func SendParams

func SendParams(message *mailer.Message) (map[string]any, error)

SendParams converts a PocketBase message into a Groundmail send request.

Types

type Mailer

type Mailer struct {
	// contains filtered or unexported fields
}

Mailer sends PocketBase messages through Groundmail.

func New

func New(opts Options) (*Mailer, error)

New builds a Mailer.

func (*Mailer) Send

func (m *Mailer) Send(message *mailer.Message) error

Send implements mailer.Mailer.

type Options

type Options struct {
	// APIKey is a Groundmail API key (gm_…). Defaults to GROUNDMAIL_API_KEY.
	APIKey string
	// BaseURL overrides the API base URL.
	BaseURL string
	// HTTPClient overrides the HTTP client.
	HTTPClient *http.Client
}

Options configures the Groundmail client.