Skip to main content

Quick start

MailSlurp is an email, SMS, messaging automation, and testing platform for developers, QA teams, and marketing teams. With MailSlurp you can create and control real email accounts and phone numbers, then automate and validate communication flows with test-focused wait functions, event workflows, and AI-powered data extraction.

Create an account and API key​

Before you run any workflow, create your account and get an API key.

  1. Create a free account in the dashboard.
  2. Generate an API key in developer settings.
  3. Pick your integration style: SDK first (fastest start) or direct REST API.
Create account

Four pillars​

Choose your starting pillar, then use the detailed playbooks below.

Email

Inboxes, domains, sending, receiving, and extraction workflows.
Open section

SMS

Provision numbers, send and receive SMS, and wait for OTP codes.
Open section

Testing

Deterministic test patterns, deliverability checks, and QA tooling.
Open section

Automation

Webhooks, routing, forwarding, aliases, auto-replies, and AI transforms.
Open section

Email​

Email is the core MailSlurp workflow: create isolated inboxes, send from real addresses, and receive reliably using wait functions or webhooks. The value proposition is control and repeatability: every workflow can run against clean inbox state and deterministic message matching.

SDK language tabs

MailSlurp supports Javascript, Java, C#, PHP, Python, Ruby, and Go SDKs, plus direct HTTP API endpoints for every feature. Some examples below are shown in a single language to keep the page readable, but equivalent operations are available across all SDKs.

Create inboxes: isolate every workflow run

When creating inboxes on demand, each run can use a unique address. This removes shared-state flakiness in tests and keeps operational automations clean.

  • Use one inbox per test run for signup/password reset/notification scenarios.
  • Keep inboxId and emailAddress as the canonical identifiers in your flow.
  • For high-volume programs, use tags or naming conventions to track ownership.
Loading...

After that pattern is working, go deeper here: Inboxes and Plus addresses.

Custom domains: production sender identity and trust

Custom domains let you send and receive using your brand domain instead of default addresses. This is important for user trust, brand consistency, and production messaging programs.

How to use it effectively:

  1. Add and verify your domain in MailSlurp.
  2. Configure required DNS records exactly as shown in the dashboard.
  3. Create domain-scoped inboxes for the exact addresses your app needs.
  4. Validate delivery and bounce behavior before scaling volume.

If you are moving from test to production messaging, continue with: Custom domains.

Send email: programmatic control over content and timing

Sending via API/SDK gives full control over recipients, subject/body, attachments, and workflow timing. This enables transactional notifications, onboarding messages, OTP links, and system alerts.

Typical usage pattern:

  • Build message payload with explicit subject and destination list.
  • Send from the inbox tied to that workflow.
  • Keep message IDs for traceability and later assertions.
Loading...

Advanced sending examples are covered in: Emails and Attachments.

Receive email: wait-based testing vs webhook-based automation

There are two primary receive models:

  • Wait methods: best for synchronous test steps ("perform action, then wait for message").
  • Webhooks: best for scalable event-driven systems (push events to your service as they happen).

In test environments, wait methods reduce flakiness when you use explicit matching and sensible timeouts.

Loading...

For production-grade event flows, then switch or extend to: Wait for methods and Webhooks.

SMS and phones​

SMS workflows in MailSlurp provide real phone numbers and deterministic receive logic, ideal for OTP/MFA, onboarding verification, and alerting paths.

Create phone numbers: establish real SMS endpoints

Phone numbers are provisioned in the dashboard and become API-controlled messaging resources. Treat each number like a workflow endpoint with clear ownership.

Best practices:

  • Use dedicated numbers per environment where possible.
  • Document number purpose (OTP, notifications, support flows).
  • Monitor inbound/outbound usage before scaling.

Create phone

Once provisioned, continue with: SMS and phone numbers.

Send SMS: transactional and verification messaging

Send SMS from your provisioned number for OTP, status updates, and transactional confirmations. Keep payloads concise and include only essential instructions or codes.

Loading...

Equivalent SDK/API support:

Then expand with filtering and webhook handling in: TXT/SMS guide.

Receive SMS: inspect and process inbound messages

Inbound SMS can be listed and inspected in code. This is useful for verification loops, support workflows, and message classification.

Loading...

Equivalent SDK/API support:

For deeper inbox/message management patterns, see: TXT/SMS guide.

Wait for SMS: deterministic OTP and verification tests

Wait functions are especially useful for OTP tests where timing is variable. Instead of fixed sleeps, wait for matching SMS content and assert the result.

Loading...

Equivalent SDK/API support:

For more wait strategies and matching patterns, continue to: Wait for methods.

Testing​

Testing is where MailSlurp stands out: clean resource setup, deterministic waits, and robust extraction patterns for realistic end-to-end messaging tests.

General test flow:

  1. Create inbox/phone resources for the run.
  2. Execute app action (signup, login, reset, notification trigger).
  3. Wait for the matching email/SMS event.
  4. Extract links/codes/content and assert expected behavior.
Wait functions and techniques: eliminate flaky async assertions

Value proposition: wait methods replace brittle sleep-based tests with condition-based synchronization.

How to use effectively:

  • Match on known constraints (inbox, unread, sender, subject, body conditions).
  • Use bounded timeouts appropriate for your environment.
  • Prefer explicit matching over "latest message" when multiple events can arrive.

Real wait-for email example:

Loading...

Real wait-for SMS example:

Loading...

Equivalent SDK/API support:

Deep dive after setup: Wait for methods and Testing overview.

Load and deliverability testing: validate reliability before production scale

Deliverability tests help teams validate whether message programs are reliably reaching destination systems and how behavior changes under load.

Use this when:

  • Launching new sender domains or message templates.
  • Running campaign or transaction load tests.
  • Monitoring regression in delivery rates over time.

Example setup call:

Loading...

Equivalent SDK/API support:

Then run your full process with: Deliverability tests.

Email auditing and quality checks: detect content issues early

Audit email content for problems that break user journeys: missing links, broken images, and content issues that reduce conversion or trust.

Use this to:

  • Validate critical links before release.
  • Catch rendering or content regressions in CI.
  • Enforce quality gates for template updates.

Example audit call:

Loading...

Equivalent SDK/API support:

Then apply the full checks in: Email feature check.

Device and browser previews: validate realistic QA flows

When your team is validating complete user journeys, browser-based no-code flows help confirm that messages are delivered and usable in real UI contexts.

Use this for:

  • Manual QA verification passes.
  • No-code tool integration.
  • Regression checks alongside code-based tests.

Continue with: Test interface.

Framework SDK techniques: Selenium, Cypress, Playwright and more

MailSlurp works with major E2E frameworks so test code can create inboxes, wait for messages, and assert extracted content inside your test pipeline.

Recommended implementation pattern:

  • Build shared helper functions for inbox/phone setup and cleanup.
  • Standardize extraction utilities for OTP codes and magic links.
  • Keep framework-specific logic focused on UI interactions only.

Framework docs:

Automation​

Automation turns messaging from manual polling into event-driven, repeatable pipelines that can route, transform, and enrich communication streams.

Core automations: webhooks, forwarding, aliasing, rules, auto-replies

These features let you route messages to the right systems and apply business logic automatically.

Feature value:

  • Webhooks: trigger backend processing in real-time.
  • Forwarding: route inbound emails to downstream recipients/systems.
  • Alias proxy: mask/relay addresses while maintaining control.
  • Routing rulesets: enforce allow/deny and policy behavior.
  • Auto-replies: respond instantly for common workflows.

Start with webhooks + one routing control, then layer additional automation features as volume grows.

Implementation docs:

AI transforms: convert unstructured messages into structured data

AI transforms let you define a schema and turn raw emails, attachments, and SMS into structured records that your systems can consume.

How it works:

  1. Define the target schema (for example invoiceNumber, total, dueDate).
  2. Configure prompt/schema-based extraction logic.
  3. Run by explicit invocation or attach to automated pipelines.
  4. Store results in MailSlurp tables and forward to downstream tools.

Example use case:

  • Parse invoice emails into structured finance fields for reconciliation and reporting workflows.

Result handling options include API retrieval, webhook delivery, and external sync workflows (for example Sheets/Airtable/Notion/CSV pipelines).

Continue here: