Java SDK
The official client of the fake-email.pro API for Java 17+, built on the JDK's HttpClient with no other dependencies, so nothing clashes with your test classpath. It covers every endpoint with immutable record models, turns errors into unchecked exceptions you can catch by type, 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.
Java 17+, no dependencies, from the jitpack.io repository; JUnit 5 and Playwright
testImplementation("pro.fake-email:fake-email-java:v0.2.0")Maven and Gradle
The SDK is published through JitPack: add the https://jitpack.io repository, then the dependency. The version is the release tag. The Java package is pro.fakeemail, models are in pro.fakeemail.models.
repositories {
mavenCentral()
maven("https://jitpack.io")
}
dependencies {
testImplementation("pro.fake-email:fake-email-java:v0.2.0")
}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 from FakeEmail.builder().apiKey(…). The API is server-to-server, without CORS: call it from the test JVM, never from the page under test.
Quickstart
import pro.fakeemail.FakeEmail;
import pro.fakeemail.WaitOptions;
import pro.fakeemail.models.Mailbox;
try (FakeEmail client = new FakeEmail()) { // reads FAKE_EMAIL_API_KEY
Mailbox mailbox = client.mailboxes().create();
System.out.println("Sign up with " + mailbox.address());
try {
// Long-polls the mailbox for up to 60 s and returns the one-time code
String code = client.waitForCode(mailbox.address(), WaitOptions.builder().subject("verification").build());
System.out.println(code);
} finally {
client.mailboxes().delete(mailbox.address());
}
}JUnit 5 and Playwright
A FakeEmail is thread-safe: one client for the test class, a fresh mailbox for every test, and waitForCode waiting across as many long polls as the timeout allows. If your tests carry a @Timeout, keep it above the wait's own (60 s by default).
import static com.microsoft.playwright.assertions.PlaywrightAssertions.assertThat;
import com.microsoft.playwright.Browser;
import com.microsoft.playwright.Page;
import com.microsoft.playwright.Playwright;
import com.microsoft.playwright.options.AriaRole;
import org.junit.jupiter.api.*;
import pro.fakeemail.FakeEmail;
import pro.fakeemail.WaitOptions;
class SignUpTest {
static final FakeEmail client = new FakeEmail();
static Playwright playwright;
static Browser browser;
Page page;
String address;
@BeforeAll
static void launch() {
playwright = Playwright.create();
browser = playwright.chromium().launch();
}
@AfterAll
static void shutdown() {
playwright.close();
client.close();
}
// A fresh mailbox for every test, deleted when the test ends
@BeforeEach
void setUp() {
page = browser.newPage();
address = client.mailboxes().create().address();
}
@AfterEach
void tearDown() {
client.mailboxes().delete(address);
page.close();
}
@Test
void signUpIsConfirmedWithTheEmailedCode() {
page.navigate("https://your-app.example/sign-up");
page.getByLabel("Email").fill(address);
page.getByRole(AriaRole.BUTTON, new Page.GetByRoleOptions().setName("Sign up")).click();
String code = client.waitForCode(address, WaitOptions.builder().subject("verification").build());
page.getByLabel("Code").fill(code);
assertThat(page.getByText("Email confirmed")).isVisible();
}
}Waiting for an email
waitForMessage(address, options)– the first message that matches thefrom,subjectand an optionalmatchpredicate ofWaitOptions. It repeats the 60-second long poll untiltimeout(60 s by default), then throwsWaitTimeoutError. Every call blocks its thread; interrupting the thread cancels it with aCancellationException.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.
SimpleMessage first = client.waitForMessage(address, WaitOptions.builder().subject("Welcome").build());
// Strictly after the first one: nothing that arrived in between is lost
SimpleMessage second = client.waitForMessage(address, WaitOptions.builder()
.after(first.id())
.match(message -> message.attachmentsCount() > 0)
.build());Methods and models
Methods are reached through accessors – mailboxes(), messages(), domains(), limits() – and the optional argument has an overload without it. listAll fetches the pages lazily as you iterate, or as a stream(); a single wait returns an Optional, empty when the server timeout passed. Models are records with Instant times; Page is pro.fakeemail.models.Page, so import Playwright's by its full name.
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 Java the classes keep these names – APIConnectionError and APITimeoutError included – and are unchecked, all extending FakeEmailError; their fields are accessors – status(), code(), rateLimit().
Configuration
import java.net.InetSocketAddress;
import java.net.ProxySelector;
import java.net.http.HttpClient;
import java.time.Duration;
import pro.fakeemail.FakeEmail;
FakeEmail client = FakeEmail.builder()
.apiKey("fep_...") // default: FAKE_EMAIL_API_KEY
.baseUrl("https://api.fake-email.pro") // default
.timeout(Duration.ofSeconds(30)) // per HTTP attempt; a wait request always gets its server timeout + 10 s
.maxRetries(2) // 0 disables retries
.userAgent("my-e2e-suite/1.4") // appended to fake-email-pro-java/<version>
.httpClient(HttpClient.newBuilder() // default: a new HttpClient
.proxy(ProxySelector.of(new InetSocketAddress("proxy.internal", 3128)))
.build())
.build();FakeEmail is AutoCloseable: closing it releases the HttpClient it created (Java 21+); one you pass in is yours to close. For a single call, client.withOptions(RequestOptions.builder().timeout(…).maxRetries(0).build()) returns a view that shares the connections. A shorter timeout there never cuts a wait short: a long poll always gets its server timeout + 10 s.
Other languages
C# / .NET, Go, JavaScript / TypeScript, PHP, Python – or every SDK and the OpenAPI document for any other language.