Changelog

The first release of the Go SDK: the module github.com/bfzli/nextmail-go, with the package nextmail. It needs Go 1.24 or later and nothing outside the standard library. It has a method for each of the 684 methods of the TypeScript SDK, in the same 53 namespaces and under the same names in Go’s casing, as fields of the client: client.Emails.Send, client.Threads.List, client.Domains.Verify. They cover everything from sending and reading mail to contacts, broadcasts, automations, the calendar, booking pages, tasks and the settings of a workspace, and a parity check proves that each one sends the same request as its TypeScript twin.

• —nextmail.New() reads NEXTMAIL_API_KEY, NEXTMAIL_ACCESS_TOKEN and NEXTMAIL_BASE_URL, and takes WithAPIKey, WithAccessToken, WithAccessTokenFunc, WithBaseURL, WithHTTPClient, WithTimeout, WithMaxRetries, WithUserAgent and WithHeader. It never fails: a missing or malformed credential is reported by client.Err() and by the first call.
• —Every method takes a context.Context first, which cancels the call or gives it a deadline. Request bodies are nextmail.Body maps that keep the field names of the API, options are functions such as nextmail.WithLimit and nextmail.WithCursor, and results are nextmail.Object values with readers such as String, Int, Bool, Time and Object.
• —Every paginated resource has List for one page, ListAll for every item as a slice, and Iterate, which fetches the next page only when it gets there. Range over its All(), or call Next, Item and Err in a plain loop.
• —Failures come back as *nextmail.Error values with Status, Type, Code, Param, DocURL, RequestID, RetryAfter, Fields and Body, and errors.Is matches them against sentinels such as ErrNotFound, ErrValidation, ErrRateLimited, ErrStepUpRequired, ErrNetwork and ErrTimeout. A mistake in the call itself matches ErrInvalidArgument and is returned before anything is sent.
• —Reads, sends and every write that is safe to repeat are retried on 408, 500, 502, 503 and 504 with backoff, and on a 429 only when its Retry-After is a minute or less. Every send carries an idempotency key that its retries reuse, and nextmail.WithIdempotencyKey sets your own.
• —An OAuth access token works in place of an API key, given as it is or by a function that runs before every request, so the token can be renewed without a new client. When a change made with a token needs a verification code, the error matches ErrStepUpRequired, and client.Security.BeginStepUp and VerifyStepUp provide one.
• —nextmail.VerifyWebhookSignature checks a webhook delivery in constant time, refuses one more than five minutes old and returns the event.
• —nextmail.NewTempMail builds a client for disposable inboxes that needs no credential, and client.Request calls an endpoint no method wraps, with the credential, timeout and retries of the client.
• —nextmail.ResolveLanguage, LanguageByCode, IsRTLLanguage, IsAPIKey, IsAccessToken and IsSealed are the helpers of the TypeScript SDK, and the constants package holds the sets of values the API uses, such as webhook events, scopes and statuses.
• —A client is safe for concurrent use. It sends a credential over plain http: only to a server on this machine, its default HTTP client follows no redirects, and printing a client, an option or an error never shows a credential.