Skip to main content
The official mailkube Go SDK wraps the whole send surface with no third-party dependencies. The standard library covers everything. It requires Go 1.23+.

Install

Get your API key

Create a key for a verified domain in the dashboard. The key is a string that starts with mk_. See Authentication for how to send it and keep it safe.

Send your first email

Every verb takes a context.Context first, so cancellation and deadlines are yours to set.

Configure the client

Go has no keyword arguments, so configuration is functional options. Anything you leave out falls back to the environment:
If you are building something on top of this SDK, set WithUserAgentSuffix to your own name/version. It follows the SDK’s own token, and the API’s required User-Agent shows both layers.
A client passed through WithHTTPClient brings its own redirect policy, and Go’s default follows redirects, rewriting a redirected PATCH or DELETE into a GET without its body. The client the SDK builds for itself refuses redirects; give an injected one a CheckRedirect that returns an error so it does the same.
Create one client and reuse it for the lifetime of your process. It is safe for concurrent use from any number of goroutines. A package-level client shared by every request handler is the intended pattern.
Your API key can send email on your behalf. Keep it server-side, injected from a secrets manager or environment variable. Never ship it in a CLI you distribute, a mobile app, or a public repository.

The response

Use email.ID to correlate the message with webhook events, and email.MessageID to thread replies.

Recipients, content and attachments

To, CC, BCC and ReplyTo are string slices. Supply HTML, Text, or both. Attachment content is raw bytes; the SDK base64-encodes it for you:
To send a saved template, set TemplateID (and optional TemplateVersion) with Variables rather than HTML/Text.

Reply threading

Pass the previous message’s MessageID in the In-Reply-To and References headers:

Idempotent sends

IdempotencyKey travels as a header, and a repeated request with the same key returns the original result instead of sending twice:
See Idempotency for the full semantics.

Scheduled sends

Set ScheduledAt to transmit later. The acknowledgment reports IsScheduled(), and the send stays manageable until it is due:
List returns one page; All walks every page lazily, following the links the API returns:
Ranging over an iterator needs go 1.23 or later in your own go.mod, not just in your toolchain. On an older module, loop on List and page.Pagination.Steps.Next instead.
Timestamps come back as the verbatim strings the server sent. Parse one with time.Parse(time.RFC3339, item.ScheduledAt). See Scheduled emails for the horizon, the listable statuses, and the plan requirement.

Your API key

client.Credential.Info returns the key the client authenticates with: its domain, organization, source-IP allowlist, plan and send-quota usage.
The key is checked exactly as a send checks it, so one call confirms a key works before your first send. A key that cannot send fails with ErrAuthentication with the error name invalid_api_key, and Checking a key lists the causes. Each call counts as a use of the key, and plan and quota figures can be up to 30 seconds old. Plan is nil when the organization has no subscription. A plan without a daily limit lists emails_per_month only, and Remaining counts recipients, not messages. The call has a rate limit of its own for each key. The client keeps the key it was built with. To use another key, build another client.

Handling errors

Branch on the category with errors.Is, and reach the envelope with errors.As:
The categories are ErrBadRequest (400), ErrAuthentication (403), ErrNotFound (404), ErrConflict (409), ErrInvalidRequest (422), ErrRateLimit (429), ErrServer (5xx) and ErrAPI for anything else. A transport failure matches ErrConnection, and everything the package returns matches ErrMailkube. apiErr.ErrorName carries the machine-readable name; see Errors for what each one means. apiErr.RequestID holds the id the API returned for that exact call. Log it, and quote it when you report a failure to support. It is what lets support find your exact call:
There are deliberately no built-in retries: a rate-limit error carries the server’s own Retry-After, a server error is safe to retry with backoff, and an idempotency key makes a retry safe.

Receiving webhooks

WebhookHandler is an http.Handler and mounts anywhere. Mount it on GET and POST: before the platform saves an endpoint it probes the URL with GET ?hub.mode=subscribe&hub.challenge=<token>, and an endpoint that does not echo the challenge is never created.
OnEvent runs inside the request and a delivery gets ten seconds. Only a 2xx counts as accepted, and an endpoint whose acceptance rate stays low is disabled automatically, so enqueue the work and return. Deduplicate on event.ID, which is stable across retries of the same delivery.
An event type this SDK version does not model arrives as *UnknownData rather than an error, and event.Raw always holds the verbatim body. mailkube.EventTypes() lists everything it does model. See Webhooks for the event catalog and the signature scheme. Two optional fields tune the handler. MaxBodyBytes caps how much of a request body it reads; zero means 1 MiB. OnError receives every rejected request, for when you want the rejection logged or shaped instead of the handler’s default response:

Logging

Silent by default. Pass WithLogger or set MAILKUBE_LOG=debug to log requests and responses; Authorization and Idempotency-Key are redacted.

Use with Gin

Gin needs nothing special. Build the client once, keep it on a small struct so handlers stay testable, and mount the webhook receiver with gin.WrapH. Register both methods: the platform probes with GET before it will save the endpoint, and r.POST alone would answer 404 to the probe:
Inside a handler, pass c.Request.Context() to Send so a canceled request cancels the call.
Gin’s Recovery middleware does not wrap a WrapH handler’s own panics into a 500 you control, and a delivery only has ten seconds. Keep OnEvent to an enqueue-and-return, and deduplicate on event.ID.

Use with Echo

Echo mounts the receiver with echo.WrapHandler. Use e.Any, not e.POST, for the same registration-probe reason:
echo.WrapHandler bypasses Echo’s own error handling, so set the handler’s OnError when you want a rejection logged or shaped. In send handlers, c.Request().Context() propagates a client disconnect into the in-flight call.

Use with Fiber

Fiber runs on fasthttp rather than net/http, which needs two adaptations. The receiver mounts through the adaptor, on All so the GET probe is answered:
Fiber’s context is not a context.Context; pass c.UserContext() to Send (c.Context() on Fiber v3) so cancellation still propagates. If you skip the adaptor and call Verify by hand, wrap the header lookup: Ctx.Get is variadic and cannot be converted to mailkube.HeaderFunc directly:
mailkube.HeaderGetter is satisfied by anything with a Get(string) string method, which is why net/http, Chi, Gin and Echo pass r.Header unchanged. HeaderFunc exists for exactly the fasthttp case.

Next steps

Webhooks

Every event WebhookHandler can hand OnEvent, with the signing scheme and retries.

API reference

The send endpoint’s full field list, error codes, and rate limits.