PocketBase
Route all PocketBase system emails through Keplars
Replace PocketBase's built-in SMTP mailer with Keplars. All system emails - password reset, email verification, OTP, login alerts - are routed through Keplars automatically with zero changes to your app logic.
Approaches
| Go Package | JSVM Hook | |
|---|---|---|
| Setup | Import + MustRegister | Drop .pb.js into pb_hooks/ |
| Retry logic | Yes (exponential backoff) | No |
| Admin API | Yes (/api/keplars/*) | No |
| Compilation | Required | None |
| Best for | Production apps | Quick integration |
Go Package
Install
go get github.com/KeplarsHQ/pocketbase-keplarsOr clone the repo and use the install script:
git clone https://github.com/KeplarsHQ/pocketbase-keplars.git
cd pocketbase-keplars
./scripts/install.shRegister the plugin
package main
import (
"log"
keplars "github.com/KeplarsHQ/pocketbase-keplars"
"github.com/pocketbase/pocketbase"
)
func main() {
app := pocketbase.New()
keplars.MustRegister(app)
if err := app.Start(); err != nil {
log.Fatal(err)
}
}Pass options to override any env var at registration time:
keplars.MustRegister(app,
keplars.WithAPIKey("kms_..."),
keplars.WithPriority(keplars.PriorityInstant),
keplars.WithFromEmail("[email protected]"),
keplars.WithFromName("Your App"),
)Set environment variables
export KEPLARS_API_KEY=kms_your_key_here
export KEPLARS_FROM_EMAIL=[email protected]
export KEPLARS_FROM_NAME="Your App"
export KEPLARS_PRIORITY=highRun
# Using Makefile
make run
# Or directly
./bin/pocketbase-example serveJSVM Hook (drop-in)
For users running PocketBase as a pre-built binary - no Go required.
Copy the hook file
mkdir -p pb_hooks
curl -o pb_hooks/keplars.pb.js \
https://raw.githubusercontent.com/KeplarsHQ/pocketbase-keplars/main/pb_hooks/keplars.pb.jsSet environment variables
export KEPLARS_API_KEY=kms_your_key_here
export KEPLARS_FROM_EMAIL=[email protected]
export KEPLARS_PRIORITY=highEnvironment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
KEPLARS_API_KEY | Yes | - | Your Keplars API key (kms_...) |
KEPLARS_FROM_EMAIL | No | PocketBase sender | Override sender address |
KEPLARS_FROM_NAME | No | PocketBase sender name | Override sender display name |
KEPLARS_PRIORITY | No | high | Default priority queue |
KEPLARS_BASE_URL | No | https://api.keplars.com | Override API base URL |
Priority Reference
| Use Case | Priority |
|---|---|
| OTP, magic links | instant |
| Password reset, login alerts | high (default) |
| Welcome, notifications | async |
| Newsletters, campaigns | bulk |
Admin API
The Go package registers three superuser-protected endpoints on your PocketBase server.
Get current configuration:
curl http://localhost:8090/api/keplars/settings \
-H "Authorization: Bearer YOUR_SUPERUSER_TOKEN"Update configuration at runtime:
curl -X PATCH http://localhost:8090/api/keplars/settings \
-H "Authorization: Bearer YOUR_SUPERUSER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"default_priority":"instant","from_email":"[email protected]"}'Send a test email:
curl -X POST http://localhost:8090/api/keplars/test \
-H "Authorization: Bearer YOUR_SUPERUSER_TOKEN" \
-H "Content-Type: application/json" \
-d '{"to":"[email protected]"}'Or using the Makefile shortcut:
make test-email [email protected] TOKEN=YOUR_SUPERUSER_TOKENScripts
The repository ships with a Makefile and shell scripts for common operations.
make install # go mod tidy + build binary
make run # start server on :8090
make clean # remove bin/
make reset # remove bin/ + pb_data/ (wipes database)
make test-email [email protected] TOKEN=<token>
make settings TOKEN=<token>chmod +x scripts/install.sh scripts/clean.sh
./scripts/install.sh # fetch deps + build
./scripts/clean.sh # remove bin/
./scripts/clean.sh --reset # remove bin/ + pb_data/How It Works
The plugin hooks into OnMailerSend - PocketBase's catch-all email hook - and replaces the default SMTP dispatch with a direct call to the Keplars REST API. The original mailer is never invoked.
All PocketBase system emails are covered automatically:
- Password reset
- Email verification
- Email change confirmation
- New device login alert
- OTP / magic link