Go SDK
The official client of the fake-email.pro API for Go, on the standard library alone with a context.Context on every call. It covers every endpoint with typed models, returns errors you can match with errors.As, retries rate limits on its own, and waits for the email of an end-to-end test – handing back its one-time code or confirmation link. Open source under the MIT license.
Go 1.23+, standard library only, context on every call; go test and playwright-go
go get github.com/fake-email-pro/fake-email-gogithub.com/fake-email-pro/fake-email-go on pkg.go.devSource on GitHub
API key
Create a key as in Quickstart and put it in the FAKE_EMAIL_API_KEY environment variable – a CI secret on a build agent. The client reads it from there, or takes it as fakeemail.WithAPIKey. The API is server-to-server, without CORS: call it from the test process, never from the page under test or a WebAssembly build.
Quickstart
package main
import (
"context"
"fmt"
"log"
fakeemail "github.com/fake-email-pro/fake-email-go"
)
func main() {
// log.Fatal skips deferred calls, so the work is in run and its defer always deletes the mailbox
if err := run(context.Background()); err != nil {
log.Fatal(err)
}
}
func run(ctx context.Context) error {
client, err := fakeemail.NewClient() // reads FAKE_EMAIL_API_KEY
if err != nil {
return err
}
mailbox, err := client.Mailboxes.Create(ctx, nil)
if err != nil {
return err
}
defer client.Mailboxes.Delete(ctx, mailbox.Address)
fmt.Println("Sign up with", mailbox.Address)
// Long-polls the mailbox for up to 60 s and returns the one-time code
code, err := client.WaitForCode(ctx, mailbox.Address, &fakeemail.WaitOptions{Subject: "verification"})
if err != nil {
return err
}
fmt.Println(code)
return nil
}go test and Playwright
One client for the package – it is safe for concurrent use – a fresh mailbox for every test, removed in t.Cleanup, and the browser driven by playwright-go. t.Context() (Go 1.24+) is cancelled when the test ends, so a wait never outlives its test.
package app_test
import (
"context"
"testing"
fakeemail "github.com/fake-email-pro/fake-email-go"
"github.com/mxschmitt/playwright-go"
)
var client = mustClient()
func mustClient() *fakeemail.Client {
c, err := fakeemail.NewClient() // FAKE_EMAIL_API_KEY from the environment of go test
if err != nil {
panic(err)
}
return c
}
// A fresh mailbox for every test, deleted when the test ends
func newInbox(t *testing.T) string {
t.Helper()
mailbox, err := client.Mailboxes.Create(context.Background(), nil)
if err != nil {
t.Fatal(err)
}
t.Cleanup(func() { client.Mailboxes.Delete(context.Background(), mailbox.Address) })
return mailbox.Address
}
func TestSignUpWithAnEmailCode(t *testing.T) {
must := func(err error) {
t.Helper()
if err != nil {
t.Fatal(err)
}
}
inbox := newInbox(t)
pw, err := playwright.Run()
must(err)
defer pw.Stop()
browser, err := pw.Chromium.Launch()
must(err)
defer browser.Close()
page, err := browser.NewPage()
must(err)
_, err = page.Goto("http://localhost:3000/sign-up")
must(err)
must(page.GetByLabel("Email").Fill(inbox))
must(page.GetByRole("button", playwright.PageGetByRoleOptions{Name: "Sign up"}).Click())
code, err := client.WaitForCode(t.Context(), inbox, &fakeemail.WaitOptions{Subject: "verification"})
must(err)
must(page.GetByLabel("Code").Fill(code))
must(playwright.NewPlaywrightAssertions().Locator(page.GetByText("Email confirmed")).ToBeVisible())
}Waiting for an email
WaitForMessage(ctx, address, opts)– the first message that matchesFrom,Subjectand an optionalMatchfunction. It repeats the 60-second long poll untilTimeout(60 s by default), then returns a*WaitTimeoutError; a cancelled context ends it withctx.Err().WaitForCodeandWaitForLink– the same, returning the code or the confirmation link the API read out of the email; a message without one is skipped.- For the next email in the same mailbox, pass
Afterwith the id of the one you have. More on the flow in Email testing.
first, err := client.WaitForMessage(ctx, address, &fakeemail.WaitOptions{Subject: "Welcome"})
if err != nil {
return err
}
// Strictly after the first one: nothing that arrived in between is lost
second, err := client.WaitForMessage(ctx, address, &fakeemail.WaitOptions{
After: first.ID,
Match: func(m *fakeemail.SimpleMessage) bool { return m.AttachmentsCount > 0 },
})Methods and models
Every method takes a context.Context first and per-call options last – WithRequestTimeout, WithRequestMaxRetries; a shorter timeout never cuts a wait short, as a long poll always gets its server timeout + 10 s. Params may be nil, and a zero field means unset. ListAll returns an iter.Seq2 to range over every page; nullable fields of the models are pointers, timestamps are time.Time.
The client has a method for each endpoint of the API; their parameters and responses are in Endpoints.
Errors and retries
Every error of the API is thrown as an APIError with the HTTP status, the error code, the message and the rate-limit headers; its subclass names the case: BadRequestError 400, AuthenticationError 401, QuotaExhaustedError 402, PermissionDeniedError 403, NotFoundError 404, ConflictError 409, RateLimitError 429, InternalServerError 5xx. What each status and code means is in Errors. A request that got no response throws APIConnectionError, and one whose HTTP attempt outlasted its timeout APITimeoutError, a subclass of it.
Retries (twice by default) wait the Retry-After of the response, or a short backoff without one. A 429 and a 503 are retried on every method, since the server refused them before doing anything – except a 503 that asks to come back in more than 5 s, which is thrown at once. A network error, a timed-out attempt, a 502, a 504 and Cloudflare's 520–524 are retried on GET and DELETE only, so a mailbox is never created twice; a retried DELETE that gets 404 counts as done, since the attempt before it went through. A wait helper waits out 429, 502–504, 520–524 and connection errors until its own deadline, and then throws WaitTimeoutError.
In Go the errors are pointer types – *fakeemail.NotFoundError and the rest – matched with errors.As. Each embeds *APIError and unwraps to it, so a match on *APIError catches them all. No response is a *fakeemail.APIConnectionError, an attempt past its timeout a *fakeemail.APITimeoutError, which unwraps to it. A cancelled context is not wrapped: you get ctx.Err() as is.
_, err := client.Mailboxes.Get(ctx, address)
var notFound *fakeemail.NotFoundError
if errors.As(err, ¬Found) {
// expired or deleted: notFound.Status == 404
}
var apiErr *fakeemail.APIError // any status, NotFoundError included
if errors.As(err, &apiErr) {
log.Printf("%d %s: %s", apiErr.Status, apiErr.Code, apiErr.Message)
}Configuration
client, err := fakeemail.NewClient(
fakeemail.WithAPIKey("fep_..."), // default: $FAKE_EMAIL_API_KEY
fakeemail.WithBaseURL("https://api.fake-email.pro"), // default
fakeemail.WithTimeout(30*time.Second), // per HTTP attempt; a wait request always gets its server timeout + 10 s
fakeemail.WithMaxRetries(2), // 0 disables retries
fakeemail.WithUserAgent("my-e2e-suite/1.0"), // appended to fake-email-pro-go/<version>
fakeemail.WithHTTPClient(&http.Client{Transport: myTransport}), // proxies, custom TLS, tracing
)NewClient returns fakeemail.ErrMissingAPIKey when there is no key. Create the client once and share it: it is safe for concurrent use.
Other languages
C# / .NET, Java, JavaScript / TypeScript, PHP, Python – or every SDK and the OpenAPI document for any other language.