Receive Email in Code with a Node.js Inbox API

Receiving email in code lets an application react to a message without someone copying it from a mailbox. A test can read a verification code; a service can process an inbound reply or attachment.

The difficult part is knowing which message to use and when it has arrived. A request to send an email can succeed before delivery, and the latest message in a shared inbox can belong to another job.

MailSlurp gives your code an email address and a private inbox API. Use a bounded wait when your script expects a particular message, or a webhook when your application needs to handle incoming email continuously.

Wait for an email in Node.js

Install mailslurp-client and set MAILSLURP_API_KEY in your environment. Save this example as receive-email.mjs and run it with node receive-email.mjs.

The script prints a newly created recipient address. Send an email to that address with the exact subject Receipt check while the script is waiting. It uses real API calls; the address exists only for this run and its configured lifetime.

import assert from "node:assert/strict";
import {
  MailSlurp,
  MatchOptionFieldEnum,
  MatchOptionShouldEnum,
} from "mailslurp-client";

const apiKey = process.env.MAILSLURP_API_KEY;
if (!apiKey) throw new Error("Set MAILSLURP_API_KEY");

const mailslurp = new MailSlurp({ apiKey });
const inbox = await mailslurp.createInboxWithOptions({ expiresIn: 600_000 });

try {
  const since = new Date();
  console.log(`Send an email to ${inbox.emailAddress} with subject: Receipt check`);
  const email = await mailslurp.waitController.waitForMatchingFirstEmail({
    inboxId: inbox.id,
    since,
    timeout: 120_000,
    unreadOnly: false,
    matchOptions: {
      matches: [{
        field: MatchOptionFieldEnum.SUBJECT,
        should: MatchOptionShouldEnum.EQUAL,
        value: "Receipt check",
      }],
    },
  });

  assert.equal(email.subject, "Receipt check");
  assert.ok(email.body, "Expected a message body");
  console.log(`Received email ID: ${email.id}`);
} finally {
  await mailslurp.inboxController.deleteInbox({ inboxId: inbox.id });
}

The request waits for a matching email until the timeout. JavaScript can perform other asynchronous work while that request is pending; it does not block the CPU. If the expected message does not arrive, the wait fails rather than silently continuing with an empty inbox.

This example uses a new inbox, an exact subject and a start time. For a reused inbox, add the sender or a request-specific subject value so an unrelated message cannot satisfy the check. See the temporary email API example for a fully automated send-and-receive round trip.

Read a code, link or attachment

Once the wait returns, use that email's ID for further API calls. The email verification code API extracts OTP candidates and shows how to reject missing or ambiguous results. Extracting the code does not validate it: submit it to your application and check the resulting account state.

For a reset or verification link, select the intended action link, check its origin and path, then continue the browser test. The Playwright email guide includes that sequence. Do not follow the first URL blindly; templates also contain logos, help links and unsubscribe links.

For an inbound processing service, inspect the expected sender, content and attachments before taking the action. Treat email content as untrusted input. Store only the message details your workflow needs, and keep usable codes and reset URLs out of shared logs.

Use webhooks for ongoing inbound processing

A wait call suits a test or short-lived script. If your service should react whenever an inbox receives mail, configure an email webhook. Your handler can retrieve the message by ID and enqueue the processing work.

Plan for repeated events and handler failures. Use the message ID to make processing idempotent, check the webhook configuration's authentication options, and record failures without exposing message content. Keep the inbox alive for as long as the service needs to receive mail.

The inbox API documentation covers mailbox configuration. For other programming languages, choose a supported SDK from the developer documentation.