📨 Postmark Go Library

Unofficial Golang Library for the Postmark API (Original fork from Keighl's Postmark)

CI / CD	Quality & Security	Docs & Meta	Community

🗂️ Table of Contents

📦 Installation

postmark requires a supported release of Go.

go get github.com/mrz1836/postmark

💡 Usage

Grab your Server Token, and your Account Token.

package main

import (
	"context"

	"github.com/mrz1836/postmark"
)

func main() {
	client := postmark.NewClient("[SERVER-TOKEN]", "[ACCOUNT-TOKEN]")

	email := postmark.Email{
		From:       "[email protected]",
		To:         "[email protected]",
		Subject:    "Reset your password",
		HTMLBody:   "...",
		TextBody:   "...",
		Tag:        "pw-reset",
		TrackOpens: true,
	}

	_, err := client.SendEmail(context.Background(), email)
	if err != nil {
		panic(err)
	}
}

📚 Documentation

View the generated documentation

Heads up! postmark is intentionally light on dependencies. The only external package it uses is the excellent testify suite—and that's just for our tests. You can drop this library into your projects without dragging along extra baggage.

Supported API Coverage

Custom HTTPClient Support

package main

import (
    "github.com/mrz1836/postmark"
    "google.golang.org/appengine"
    "google.golang.org/appengine/urlfetch"
)

// ....

client := postmark.NewClient("[SERVER-TOKEN]", "[ACCOUNT-TOKEN]")

ctx := appengine.NewContext(req)
client.HTTPClient = urlfetch.Client(ctx)

// ...

Development Setup (Getting Started)

Install MAGE-X build tool for development:

# Install MAGE-X for development and building
go install github.com/mrz1836/mage-x/cmd/magex@latest
magex update:install

Library Deployment

This project uses goreleaser for streamlined binary and library deployment to GitHub. To get started, install it via:

brew install goreleaser

The release process is defined in the .goreleaser.yml configuration file.

Then create and push a new Git tag using:

magex version:bump bump=patch push

This process ensures consistent, repeatable releases with properly versioned artifacts and citation metadata.

Build Commands

View all build commands

magex help

GitHub Workflows

🎛️ The Workflow Control Center

All GitHub Actions workflows in this repository are powered by configuration files: .env.base (default configuration) and optionally .env.custom (project-specific overrides) – your one-stop shop for tweaking CI/CD behavior without touching a single YAML file! 🎯

Configuration Files:

.env.base – Default configuration that works for most Go projects
.env.custom – Optional project-specific overrides

This magical file controls everything from:

🚀 Go version matrix (test on multiple versions or just one)
🏃 Runner selection (Ubuntu or macOS, your wallet decides)
🔬 Feature toggles (coverage, fuzzing, linting, race detection, benchmarks)
🛡️ Security tool versions (gitleaks, nancy, govulncheck)
🤖 Auto-merge behaviors (how aggressive should the bots be?)
🏷️ PR management rules (size labels, auto-assignment, welcome messages)

Pro tip: Want to disable code coverage? Just add ENABLE_CODE_COVERAGE=false to your .env.custom to override the default in .env.base and push. No YAML archaeology required!

Workflow Name	Description
auto-merge-on-approval.yml	Automatically merges PRs after approval and all required checks, following strict rules.
codeql-analysis.yml	Analyzes code for security vulnerabilities using GitHub CodeQL.
dependabot-auto-merge.yml	Automatically merges Dependabot PRs that meet all requirements.
fortress.yml	Runs the GoFortress security and testing workflow, including linting, testing, releasing, and vulnerability checks.
pull-request-management.yml	Labels PRs by branch prefix, assigns a default user if none is assigned, and welcomes new contributors with a comment.
scorecard.yml	Runs OpenSSF Scorecard to assess supply chain security.
stale.yml	Warns about (and optionally closes) inactive issues and PRs on a schedule or manual trigger.
sync-labels.yml	Keeps GitHub labels in sync with the declarative manifest at `.github/labels.yml`.

Updating Dependencies

To update all dependencies (Go modules, linters, and related tools), run:

magex deps:update

This command ensures all dependencies are brought up to date in a single step, including Go modules and any managed tools. It is the recommended way to keep your development environment and CI in sync with the latest versions.

Examples & Tests

🧪 Examples & Tests

All unit tests and fuzz tests run via GitHub Actions and use Go version 1.18.x. View the configuration file.

Run all tests (fast):

magex test

Run all tests with race detector (slower):

magex test:race

⚡ Benchmarks

Run the Go benchmarks:

magex bench

📊 Performance Results

All benchmarks measure real API client performance including HTTP request setup, JSON marshaling/unmarshalling, and response processing against mock servers. Results collected on Apple M1 Max (10 cores).

🎯 Performance Overview

Metric	Value	Description
Fastest Operation	36.7 µs	Get Bounced Tags
Average Latency	41.2 µs	Across all 47 operations
Throughput	~24,000 ops/sec	Per operation average
Memory Efficiency	7.7 KB/op	Average memory usage
Allocations	97 allocs/op	Average per operation

Bounce API Performance

Operation	Latency (µs)	Throughput (ops/sec)	Memory	Allocs
Get Delivery Stats	38.0	26,300	6.8 KB	86
Get Bounces	41.6	24,000	7.8 KB	110
Get Bounce	40.4	24,800	7.1 KB	89
Get Bounce Dump	37.4	26,700	6.6 KB	84
Activate Bounce	39.9	25,100	7.2 KB	92
Get Bounced Tags	36.7	27,200	6.6 KB	85

Data Removal API Performance

Operation	Latency (µs)	Throughput (ops/sec)	Memory	Allocs
Create Data Removal	41.5	24,100	7.6 KB	100
Get Data Removal Status	38.6	25,900	6.8 KB	86

Domains API Performance

Operation	Latency (µs)	Throughput (ops/sec)	Memory	Allocs
Get Domains	40.2	24,900	7.2 KB	101
Get Domain	41.9	23,900	7.3 KB	89
Create Domain	41.3	24,200	7.8 KB	100
Edit Domain	41.7	24,000	8.3 KB	107
Delete Domain	38.2	26,200	7.1 KB	89
Verify DKIM Status	39.6	25,200	7.4 KB	91
Verify Return Path	39.2	25,500	7.4 KB	90
Rotate DKIM	40.2	24,900	7.6 KB	93

Inbound Rules Triggers API Performance

Operation	Latency (µs)	Throughput (ops/sec)	Memory	Allocs
Get Inbound Rule Triggers	39.8	25,100	7.1 KB	101
Create Inbound Rule Trigger	41.0	24,400	7.6 KB	99
Delete Inbound Rule Trigger	40.4	24,700	6.7 KB	84

Message Streams API Performance

Operation	Latency (µs)	Throughput (ops/sec)	Memory	Allocs
List Message Streams	44.4	22,500	7.4 KB	93
Get Message Stream	42.6	23,500	7.0 KB	89
Edit Message Stream	46.8	21,400	8.1 KB	106
Create Message Stream	44.5	22,500	8.1 KB	104
Archive Message Stream	40.4	24,800	6.8 KB	86
Unarchive Message Stream	42.6	23,500	7.1 KB	90

Messages API Performance

Operation	Latency (µs)	Throughput (ops/sec)	Memory	Allocs
Get Outbound Messages Clicks	47.5	21,100	8.5 KB	118
Get Outbound Message Clicks	43.2	23,100	7.9 KB	109

Sender Signatures API Performance

Operation	Latency (µs)	Throughput (ops/sec)	Memory	Allocs
Get Sender Signatures	40.6	24,600	7.3 KB	104
Get Sender Signature	40.6	24,600	7.5 KB	92
Create Sender Signature	42.2	23,700	8.1 KB	101
Edit Sender Signature	47.1	21,200	8.6 KB	108
Delete Sender Signature	38.8	25,800	7.1 KB	89
Resend Signature Confirmation	39.0	25,700	7.2 KB	90

Stats API Performance

Operation	Latency (µs)	Throughput (ops/sec)	Memory	Allocs
Get Click Counts	40.3	24,800	7.4 KB	103
Get Browser Family Counts	42.2	23,700	7.6 KB	103
Get Click Location Counts	42.8	23,400	7.4 KB	103
Get Click Platform Counts	42.0	23,800	7.5 KB	103
Get Email Client Counts	41.3	24,200	7.6 KB	103

Templates API Performance

Operation	Latency (µs)	Throughput (ops/sec)	Memory	Allocs
Get Template	39.9	25,100	7.5 KB	92
Get Templates	41.3	24,200	7.5 KB	103
Get Templates Filtered	40.0	25,000	7.4 KB	103
Create Template	44.7	22,400	7.9 KB	99
Edit Template	42.5	23,500	8.4 KB	106
Delete Template	39.3	25,500	7.1 KB	89
Validate Template	44.9	22,300	8.5 KB	110
Send Templated Email	44.2	22,600	8.8 KB	110
Send Templated Email Batch	46.1	21,700	9.0 KB	117
Push Templates	42.9	23,300	7.9 KB	105

Note: All benchmarks use mock HTTP servers for consistent, reproducible measurements. Real-world performance will vary based on network latency and Postmark API response times.

🛠️ Code Standards

Read more about this Go project's code standards.

🤖 AI Compliance

This project documents expectations for AI assistants using a few dedicated files:

AGENTS.md — canonical rules for coding style, workflows, and pull requests used by Codex.
CLAUDE.md — quick checklist for the Claude agent.
.cursorrules — machine-readable subset of the policies for Cursor and similar tools.
sweep.yaml — rules for Sweep, a tool for code review and pull request management.

Edit AGENTS.md first when adjusting these policies, and keep the other files in sync within the same pull request.

👥 Maintainers


MrZ

🤝 Contributing

View the contributing guidelines and please follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 427 Commits
.github		.github
.vscode		.vscode
examples		examples
.cursorrules		.cursorrules
.devcontainer.json		.devcontainer.json
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitpod.yml		.gitpod.yml
.golangci.json		.golangci.json
.goreleaser.yml		.goreleaser.yml
LICENSE		LICENSE
README.md		README.md
bounce.go		bounce.go
bounce_fuzz_test.go		bounce_fuzz_test.go
bounce_test.go		bounce_test.go
codecov.yml		codecov.yml
data_removals.go		data_removals.go
data_removals_test.go		data_removals_test.go
domains.go		domains.go
domains_test.go		domains_test.go
email.go		email.go
email_fuzz_test.go		email_fuzz_test.go
email_test.go		email_test.go
events.go		events.go
events_test.go		events_test.go
go.mod		go.mod
go.sum		go.sum
helpers.go		helpers.go
helpers_test.go		helpers_test.go
inbound_rules_triggers.go		inbound_rules_triggers.go
inbound_rules_triggers_test.go		inbound_rules_triggers_test.go
message_streams.go		message_streams.go
message_streams_test.go		message_streams_test.go
messages_inbound.go		messages_inbound.go
messages_inbound_test.go		messages_inbound_test.go
messages_outbound.go		messages_outbound.go
messages_outbound_test.go		messages_outbound_test.go
postmark.go		postmark.go
postmark_fuzz_test.go		postmark_fuzz_test.go
postmark_test.go		postmark_test.go
sender_signatures.go		sender_signatures.go
sender_signatures_test.go		sender_signatures_test.go
server.go		server.go
server_test.go		server_test.go
servers.go		servers.go
servers_test.go		servers_test.go
stats.go		stats.go
stats_test.go		stats_test.go
suppressions.go		suppressions.go
suppressions_test.go		suppressions_test.go
templates.go		templates.go
templates_fuzz_test.go		templates_fuzz_test.go
templates_test.go		templates_test.go
test_router.go		test_router.go
test_router_test.go		test_router_test.go
webhooks.go		webhooks.go
webhooks_test.go		webhooks_test.go

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

Repository files navigation

📨 Postmark Go Library

🗂️ Table of Contents

📦 Installation

💡 Usage

📚 Documentation

🎛️ The Workflow Control Center

Examples & Tests

🧪 Examples & Tests

⚡ Benchmarks

📊 Performance Results

🎯 Performance Overview

🛠️ Code Standards

🤖 AI Compliance

👥 Maintainers

🤝 Contributing

How can I help?

📝 License

About

Uh oh!

Releases 30

Sponsor this project

Uh oh!

Packages

Uh oh!

Languages

Uh oh!

License

mrz1836/postmark

Folders and files

Latest commit

History

Repository files navigation

📨 Postmark Go Library

🗂️ Table of Contents

📦 Installation

💡 Usage

📚 Documentation

🎛️ The Workflow Control Center

Examples & Tests

🧪 Examples & Tests

⚡ Benchmarks

📊 Performance Results

🎯 Performance Overview

🛠️ Code Standards

🤖 AI Compliance

👥 Maintainers

🤝 Contributing

How can I help?

📝 License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 30

Sponsor this project

Uh oh!

Packages 0

Uh oh!

Languages

Packages