Getting Started

Create an ephemeral inbox, send a message, wait for it, and run deterministic assertions in your CI pipeline.

A typical Email Testing CI run creates an ephemeral inbox, sends a test message, waits for the newest matching message, checks assertions, and deletes the inbox.

Call Create Ephemeral Inbox.
Send a message to the returned address through SMTP or the Email API.
Call Wait for Message. The default wait is 20 seconds and timeout_ms is capped at 40 seconds.
Call Run Assertions for the returned message.
Call Delete Inbox.

GitHub Actions

yaml

- name: Wait for captured email
  env:
    MAILEROO_API_KEY: ${{ secrets.MAILEROO_API_KEY }}
  run: |
    curl --fail-with-body --silent --show-error \
      -X POST "https://api.maileroo.com/v1/email-testing/wait/messages" \
      -H "Authorization: Bearer $MAILEROO_API_KEY" \
      -H "Content-Type: application/json" \
      -d "{\"mailbox_id\":\"$MAILBOX_ID\",\"subject_contains\":\"Verify\",\"timeout_ms\":40000}" \
      > message.json

Assertion types

See Run Assertions for every assertion type, its accepted values, and analysis requirements.

Assertions that depend on analysis return a failed result with an unavailable message when that analysis is not present. Unknown assertion types and invalid values are reported in the result rather than changing the HTTP status.

Node.js

const response = await fetch(`${baseUrl}/messages/${messageId}/assertions`, {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    assertions: [
      { type: "subject_contains", value: "Verify" },
      { type: "spf_eq", value: "pass" },
      { type: "size_lte", value: 200000 },
    ],
  }),
});
const report = await response.json();
if (!report.data.pass) process.exit(1);

Jest

This example creates and removes its own ephemeral inbox. Set MAILEROO_API_KEY, MAILEROO_SMTP_USER, and MAILEROO_SMTP_PASSWORD in the CI environment.

import nodemailer from "nodemailer";

const baseUrl = "https://api.maileroo.com/v1/email-testing";
const headers = {
  Authorization: `Bearer ${process.env.MAILEROO_API_KEY}`,
  "Content-Type": "application/json",
};

test("captures the confirmation email", async () => {
  const created = await fetch(`${baseUrl}/mailboxes/ephemeral`, {
    method: "POST",
    headers,
    body: JSON.stringify({}),
  });
  const { data: inbox } = await created.json();

  try {
    const transport = nodemailer.createTransport({
      host: "smtp.sandbox.maileroo.io",
      port: 587,
      secure: false,
      auth: {
        user: process.env.MAILEROO_SMTP_USER,
        pass: process.env.MAILEROO_SMTP_PASSWORD,
      },
    });
    await transport.sendMail({
      from: "[email protected]",
      to: inbox.address,
      subject: "Verify your account",
      text: "Your verification code is 123456.",
    });

    const waited = await fetch(`${baseUrl}/wait/messages`, {
      method: "POST",
      headers,
      body: JSON.stringify({
        mailbox_id: inbox.id,
        subject_contains: "Verify",
        timeout_ms: 40000,
      }),
    });
    const { data: message } = await waited.json();
    const checked = await fetch(`${baseUrl}/messages/${message.id}/assertions`, {
      method: "POST",
      headers,
      body: JSON.stringify({
        assertions: [
          { type: "subject_contains", value: "Verify" },
          { type: "recipient_eq", value: inbox.address },
        ],
      }),
    });
    const { data: report } = await checked.json();
    expect(report.pass).toBe(true);
  } finally {
    await fetch(`${baseUrl}/mailboxes/${inbox.id}`, {
      method: "DELETE",
      headers,
    });
  }
});

Python

python

import requests

report = requests.post(
    f"{base_url}/messages/{message_id}/assertions",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"assertions": [{"type": "subject_contains", "value": "Verify"}]},
).json()["data"]
assert report["pass"], report["results"]

pytest

Set the same API-key and SMTP environment variables as in the Jest example.

python

import os

import requests
import smtplib
from email.message import EmailMessage

BASE = "https://api.maileroo.com/v1/email-testing"
HEADERS = {
    "Authorization": f"Bearer {os.environ['MAILEROO_API_KEY']}",
    "Content-Type": "application/json",
}

def test_confirmation_email():
    inbox = requests.post(f"{BASE}/mailboxes/ephemeral", headers=HEADERS, json={}).json()["data"]
    try:
        message = EmailMessage()
        message["From"] = "[email protected]"
        message["To"] = inbox["address"]
        message["Subject"] = "Verify your account"
        message.set_content("Your verification code is 123456.")
        with smtplib.SMTP("smtp.sandbox.maileroo.io", 587) as smtp:
            smtp.starttls()
            smtp.login(os.environ["MAILEROO_SMTP_USER"], os.environ["MAILEROO_SMTP_PASSWORD"])
            smtp.send_message(message)

        captured = requests.post(
            f"{BASE}/wait/messages",
            headers=HEADERS,
            json={"mailbox_id": inbox["id"], "subject_contains": "Verify", "timeout_ms": 40000},
        ).json()["data"]
        report = requests.post(
            f"{BASE}/messages/{captured['id']}/assertions",
            headers=HEADERS,
            json={"assertions": [
                {"type": "subject_contains", "value": "Verify"},
                {"type": "recipient_eq", "value": inbox["address"]},
            ]},
        ).json()["data"]
        assert report["pass"], report["results"]
    finally:
        requests.delete(f"{BASE}/mailboxes/{inbox['id']}", headers=HEADERS)

PreviousDownload Artifact Next Wait for Message

- name: Wait for captured email env: MAILEROO_API_KEY: ${{ secrets.MAILEROO_API_KEY }} run: | curl --fail-with-body --silent --show-error \ -X POST "https://api.maileroo.com/v1/email-testing/wait/messages" \ -H "Authorization: Bearer $MAILEROO_API_KEY" \ -H "Content-Type: application/json" \ -d "{\"mailbox_id\":\"$MAILBOX_ID\",\"subject_contains\":\"Verify\",\"timeout_ms\":40000}" \ > message.json

Assertion types

See Run Assertions for every assertion type, its accepted values, and analysis requirements.

Node.js

const response = await fetch(`${baseUrl}/messages/${messageId}/assertions`, {
  method: "POST",
  headers: { Authorization: `Bearer ${apiKey}`, "Content-Type": "application/json" },
  body: JSON.stringify({
    assertions: [
      { type: "subject_contains", value: "Verify" },
      { type: "spf_eq", value: "pass" },
      { type: "size_lte", value: 200000 },
    ],
  }),
});
const report = await response.json();
if (!report.data.pass) process.exit(1);

Jest

This example creates and removes its own ephemeral inbox. Set MAILEROO_API_KEY, MAILEROO_SMTP_USER, and MAILEROO_SMTP_PASSWORD in the CI environment.

import nodemailer from "nodemailer";

const baseUrl = "https://api.maileroo.com/v1/email-testing";
const headers = {
  Authorization: `Bearer ${process.env.MAILEROO_API_KEY}`,
  "Content-Type": "application/json",
};

test("captures the confirmation email", async () => {
  const created = await fetch(`${baseUrl}/mailboxes/ephemeral`, {
    method: "POST",
    headers,
    body: JSON.stringify({}),
  });
  const { data: inbox } = await created.json();

  try {
    const transport = nodemailer.createTransport({
      host: "smtp.sandbox.maileroo.io",
      port: 587,
      secure: false,
      auth: {
        user: process.env.MAILEROO_SMTP_USER,
        pass: process.env.MAILEROO_SMTP_PASSWORD,
      },
    });
    await transport.sendMail({
      from: "[email protected]",
      to: inbox.address,
      subject: "Verify your account",
      text: "Your verification code is 123456.",
    });

    const waited = await fetch(`${baseUrl}/wait/messages`, {
      method: "POST",
      headers,
      body: JSON.stringify({
        mailbox_id: inbox.id,
        subject_contains: "Verify",
        timeout_ms: 40000,
      }),
    });
    const { data: message } = await waited.json();
    const checked = await fetch(`${baseUrl}/messages/${message.id}/assertions`, {
      method: "POST",
      headers,
      body: JSON.stringify({
        assertions: [
          { type: "subject_contains", value: "Verify" },
          { type: "recipient_eq", value: inbox.address },
        ],
      }),
    });
    const { data: report } = await checked.json();
    expect(report.pass).toBe(true);
  } finally {
    await fetch(`${baseUrl}/mailboxes/${inbox.id}`, {
      method: "DELETE",
      headers,
    });
  }
});

Python

python

import requests

report = requests.post(
    f"{base_url}/messages/{message_id}/assertions",
    headers={"Authorization": f"Bearer {api_key}"},
    json={"assertions": [{"type": "subject_contains", "value": "Verify"}]},
).json()["data"]
assert report["pass"], report["results"]

pytest

Set the same API-key and SMTP environment variables as in the Jest example.

python

import os

import requests
import smtplib
from email.message import EmailMessage

BASE = "https://api.maileroo.com/v1/email-testing"
HEADERS = {
    "Authorization": f"Bearer {os.environ['MAILEROO_API_KEY']}",
    "Content-Type": "application/json",
}

def test_confirmation_email():
    inbox = requests.post(f"{BASE}/mailboxes/ephemeral", headers=HEADERS, json={}).json()["data"]
    try:
        message = EmailMessage()
        message["From"] = "[email protected]"
        message["To"] = inbox["address"]
        message["Subject"] = "Verify your account"
        message.set_content("Your verification code is 123456.")
        with smtplib.SMTP("smtp.sandbox.maileroo.io", 587) as smtp:
            smtp.starttls()
            smtp.login(os.environ["MAILEROO_SMTP_USER"], os.environ["MAILEROO_SMTP_PASSWORD"])
            smtp.send_message(message)

        captured = requests.post(
            f"{BASE}/wait/messages",
            headers=HEADERS,
            json={"mailbox_id": inbox["id"], "subject_contains": "Verify", "timeout_ms": 40000},
        ).json()["data"]
        report = requests.post(
            f"{BASE}/messages/{captured['id']}/assertions",
            headers=HEADERS,
            json={"assertions": [
                {"type": "subject_contains", "value": "Verify"},
                {"type": "recipient_eq", "value": inbox["address"]},
            ]},
        ).json()["data"]
        assert report["pass"], report["results"]
    finally:
        requests.delete(f"{BASE}/mailboxes/{inbox['id']}", headers=HEADERS)