Quickstart

By the end of this page you will have a mailbox, an API key, and a test that waits for an email and reads its body.

1. Create an account at app.mailcatchr.com/signup. The free plan needs no card and includes one mailbox with full API access.

2. Create a mailbox. New accounts come with one already. Its subdomain is shown on the mailbox page, for example acme-ci.mailcatchr.com. Anything sent to any address on that subdomain lands in the mailbox.

3. Issue an API key. Open Workspace settings → API keys → New key. Choose which mailboxes the key may read (all, or a fixed set). The key is shown once; store it as a secret in your CI system. Keys look like mc_live_….

4. Send yourself an email. From any mail account, send a message to alice@<your-subdomain>.mailcatchr.com. It appears in the dashboard within a few seconds. Your application does the same thing in tests: it sends mail exactly as it does in production, just to an address on your subdomain.

5. Wait for it from code. The call below blocks until a message to that address arrives, then returns its summary.

   curl

   curl -H "Authorization: Bearer $MAILCATCHR_API_KEY" \
     "https://api.mailcatchr.com/v1/mailboxes/$MAILBOX_ID/messages/await?to=alice@acme-ci.mailcatchr.com&timeout=30"

   A 200 carries the message summary. A 204 means nothing matched within 30 seconds.

   TypeScript

   import { createClient } from "@mailcatchr/sdk";
   
   const mc = createClient({ apiKey: process.env.MAILCATCHR_API_KEY! });
   
   const summary = await mc.messages.await(mailboxId, {
     to: "alice@acme-ci.mailcatchr.com",
     timeoutSeconds: 30,
   });
   if (!summary) throw new Error("No email arrived in 30 s");
   
   const message = await mc.messages.get(mailboxId, summary.id);
   console.log(message.subject, message.textBody);

   C#

   using var mc = new MailcatchrClient(new MailcatchrClientOptions
   {
       ApiKey = Environment.GetEnvironmentVariable("MAILCATCHR_API_KEY")!,
   });
   
   var summary = await mc.AwaitMessageAsync(mailboxId,
       to: "alice@acme-ci.mailcatchr.com",
       timeout: TimeSpan.FromSeconds(30));
   if (summary is null) throw new Exception("No email arrived in 30 s");
   
   var message = await mc.GetMessageAsync(mailboxId, summary.Id);
   Console.WriteLine($"{message.Subject}: {message.TextBody}");

6. Put it in a test. The guides show the full pattern for Playwright, Cypress and xUnit: trigger the email from the app under test, wait for it, pull the link or code out of the body, and continue.

Where to find things

You need	Where it is
Mailbox id and subdomain	Mailbox page, top of the screen
API keys	Workspace settings → API keys
IMAP and POP3 credentials	Mailbox settings → Access credentials
Authenticators for two-factor codes	Tools → Authenticators
Webhook interceptors	Tools → Webhook Interceptor
Outbound sending and wallet	Workspace settings → Billing