Mailtrap Go client

The official Go client library for the Mailtrap email delivery platform — transactional and bulk sending, email sandbox (testing), and email marketing.

Prerequisites

To get the most out of this Mailtrap.io Go SDK:

• Create a Mailtrap account
• Verify your domain
• Create an API token

Installation

go get github.com/mailtrap/mailtrap-go

Requires Go 1.23 or newer.

Usage

Create a client with your API token:

client, err := mailtrap.NewClient("your-api-token")
if err != nil {
	log.Fatal(err)
}

Sandbox vs Production (easy switching)

Mailtrap lets you test safely in the Email Sandbox and then switch to Production sending with a single flag. In sandbox mode Send captures the email in a sandbox instead of delivering it to real recipients.

Keep the sandbox ID configured and toggle WithSandbox from configuration — the ID is ignored outside sandbox mode, so the exact same code switches environments without touching any call site:

isSandbox := os.Getenv("MAILTRAP_USE_SANDBOX") == "true"

client, err := mailtrap.NewClient("your-api-token",
	mailtrap.WithSandbox(isSandbox),
	mailtrap.WithSandboxID(3000001), // ignored unless sandbox mode is on
)
if err != nil {
	log.Fatal(err)
}

resp, _, err := client.Send(context.Background(), &mailtrap.SendRequest{
	From:    mailtrap.Address{Email: "sender@example.com", Name: "Example"},
	To:      []mailtrap.Address{{Email: "recipient@example.com"}},
	Subject: "Hello from mailtrap-go",
	Text:    "Captured by the sandbox when MAILTRAP_USE_SANDBOX=true.",
})

Supported functionality & Examples

Email API (sending):

• Transactional, bulk & batch sending — text/HTML, templates, attachments, categories, custom variables & headers — examples/sending

Email API (management):

• Sending domain management — DNS setup instructions & company info — examples/sending-domains
• Suppression management — the do-not-send list of bounces, complaints & unsubscribes — examples/suppressions
• Sending stats — aggregated, or grouped by domain, category, ESP & date — examples/stats
• Email logs — filter & cursor-paginate sent messages, inspect delivery events — examples/email-logs
• Webhook management — create, list, update & delete event webhooks — examples/webhooks
• Email template management — create, list, update & delete templates — examples/email-templates

Email Sandbox (Testing):

• Sandbox sending — single & batch — examples/sandbox-sending
• Project management — examples/projects
• Sandbox (inbox) management & actions — examples/sandboxes
• Message management & inspection — spam report, HTML analysis, headers, raw bodies — examples/messages
• Attachment operations — examples/attachments

Account & organization management:

• Accounts — list the accounts a token can access — examples/accounts
• Account accesses — list & remove user/invite/token access — examples/account-accesses
• Permissions — list resources & bulk-update access permissions — examples/permissions
• API token management — list, create, get, reset & delete — examples/api-tokens
• Billing — current billing-cycle usage across Sandbox, Sending & Marketing — examples/billing
• Organization sub-accounts — list & create — examples/sub-accounts

Contact management:

• Contacts — create, get, update (upsert) & delete by ID or email — examples/contacts
• Contact events — record custom events for a contact — examples/contact-events
• Contact lists — create, list, get, rename & delete — examples/contact-lists
• Contact fields — manage custom fields (text, number, boolean, date) — examples/contact-fields
• Contact imports — bulk-import contacts (async job) — examples/contact-imports
• Contact exports — export contacts with filters (async job) — examples/contact-exports

Errors

Non-2xx responses decode into typed errors that work with errors.As:

_, _, err := client.Projects.List(ctx)

var ve *mailtrap.ValidationError
if errors.As(err, &ve) {
	fmt.Println(ve.Fields) // field -> messages
}

var rle *mailtrap.RateLimitError
if errors.As(err, &rle) {
	time.Sleep(rle.RetryAfter)
}

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/mailtrap/mailtrap-go. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Code of Conduct.

License

This library is released under the MIT License.