Install
Get your API key
Create a key for a verified domain in the dashboard. The key is a string that starts withmk_. See Authentication for how to send it and keep it safe.
Send your first email
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:WithUserAgentSuffix to your own name/version. It follows the SDK’s own token, and the API’s required User-Agent shows both layers.
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.
The response
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:
TemplateID (and optional TemplateVersion) with Variables rather than HTML/Text.
Reply threading
Pass the previous message’sMessageID 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:
Scheduled sends
SetScheduledAt 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:
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.
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 witherrors.Is, and reach the envelope with errors.As:
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:
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.
*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. PassWithLogger 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 withgin.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:
c.Request.Context() to Send so a canceled request cancels the call.
Use with Echo
Echo mounts the receiver withecho.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 thannet/http, which needs two adaptations. The receiver mounts through the adaptor, on All so the GET probe is answered:
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.