Skip to content
MailPier Inbox

Quick start

Your team has an account (for example acme) with one or more environments. Every account has main; add others such as qa or staging on main's Settings page. Mail is kept for the environment's retention period (15 minutes to 12 hours, 24 hours on the Business plan; 12 hours by default, 15 minutes on Free), and permanently deleted when the retention period ends (within about 5 minutes). On the Team plan (one domain) and the Business plan (up to 5) you can also receive on your own domain, such as anything@qa.mail-test.acme.com: see Your own domain.

Addresses

AddressGoes to
anything@qa.acme.mailpier.ioenvironment qa (and main)
jane.doe@contoso.com.qa.acme.mailpier.iothe same, shown as "intended for jane.doe@contoso.com"
anything@acme.mailpier.iomain
anything@qaa.acme.mailpier.iomain, marked "sent to unknown environment qaa" (a typo is never refused)

The part before the @ is yours to choose, so give each test its own address. The address is read from the right: mailpier.io (or any of gather-io.net, gather-io.com), then your account, then the environment if one of that name exists; everything further left is free. So you can keep whole real addresses: point a copy of a production database at your inbox in one statement, and every mail still says who it was meant for:

-- Run on the TEST copy only. jane.doe@contoso.com -> jane.doe@contoso.com.qa.acme.mailpier.io
-- Skips NULL, empty and non-addresses, and is safe to run twice.
UPDATE dbo.Users
SET Email = LTRIM(RTRIM(Email)) + '.qa.acme.mailpier.io'
WHERE Email LIKE '%_@_%'
  AND Email NOT LIKE '%.qa.acme.mailpier.io';

main is the account-wide inbox: it shows the mail of every environment. Any other environment shows only its own addresses. Environment names are 2-30 characters a-z, 0-9 and '-' (qa, dev, uat, test, stg, prod are fine), but not a top-level-domain name such as com, net, org, io, co, uk, de, info, app.

  1. Open your environment, go to API keys and create a key. It is shown once; store it as a secret. A key reads its own environment only.
  2. Make your app send mail to a fresh address (or ask the API for a random one).
  3. Wait for the mail and read its links and one-time codes.

Who sees what

People are added per environment on its Settings page. What they see depends on where they are added:

RoleAdded inSeesCan also
Readeran environment, e.g. qaqa's mail onlyread and delete qa's mail
Manageran environment, e.g. qaqa's mail onlymanage qa's API keys, settings and members
Account-wide readermainthe mail of EVERY environmentread and delete it
Account adminmaineverythingmanage the whole account: environments, members, billing, own domains
API keyan environmentthat environment's mail only (a key made in main: every environment's mail)what the API allows

So to give someone access to one environment only, add them in that environment, not in main. Each environment's Settings page lists who else sees its mail (the account admins and account-wide readers), and the inbox shows what you see.

Email check report

Every message gets an email check report, shown on the message page, as a pass/warn/fail badge in the inbox ("Check: warn") and as qa in the API's message JSON ({"status":"warn","checks":[{"id":"links.http","status":"warn","title":"...","detail":"..."}],"template":{...}}). The status is the worst check; info checks never change it. On every plan.

Check (id)What it looks at
auth.spf, auth.dkim, auth.dmarc, auth.arcThe sender authentication our mail server did on arrival: fail on a failed SPF/DKIM/DMARC, warn on a missing record or a DKIM signature that does not match the From domain.
spamThe spam score: clean = pass, suspect = warn, spam = fail, with the rules that scored.
content.parts, content.text-matches-htmlAn HTML part without a plain-text part (warn); a text part that says something else than the HTML (warn).
content.placeholdersUnfilled merge fields such as {{first_name}}, ${orderId}, *|FNAME|*, "Hi undefined", "lorem ipsum" in the subject, text, HTML or links (fail).
size.html, size.messageHTML over 100 KB (warn: Gmail clips at about 102 KB); a message over 10 MB (fail).
images.altImages without an alt attribute (warn; tracking pixels are ignored, alt="" is fine for decoration).
links.broken, links.http, links.internalMalformed links (htps://, spaces, relative links, empty or # hrefs), http:// links (warn), links to localhost, private addresses or staging/dev/qa hosts in a mail from a production sender (warn).
headers.from, headers.reply-to, subjectA missing or invalid From, a From domain that is not real, an invalid Reply-To; an empty subject or one over 78 characters (warn).
content.preheader, headers.list-unsubscribeFor information: the preheader text, and whether bulk-looking mail has a List-Unsubscribe header (with one-click).
templateFor information: whether the email changed since the previous one of its template (see below).

Check links (message page button, or POST /v1/messages/{id}/check-links): follows every web link of the message (at most 50, 5 seconds each, up to 5 redirects) and reports the final status of each. Internal and private addresses are never contacted ("blocked"). On every plan, per account: 5 per month on Free, 20 per hour on Starter and Team, 60 per hour on Business (a message without web links is not counted).

Template change detection: notice when your emails change

Your app sends the same kinds of emails over and over: "Reset your password", "Verify your email", "Your invoice". MailPier recognises each kind (a template) by its sender and subject, and compares every new one with the last one it saw. When the wording, links, images or attachments change, the email gets a changed badge in the inbox and the message page shows exactly what is different (the lines removed and added). Things that change for every recipient (names, codes, dates, order numbers) are ignored, so you only see real changes.

Why it matters: a template edit, a broken merge field (Hello {first_name}), a link still pointing at staging, or a missing PDF attachment gets caught in testing, before your customers see it.

Example: in the last release, "Reset your password" said "The link expires in 24 hours" and linked to app.acme.com/reset. In this build it says "The link expires in 1 hour" and links to staging.acme.com/reset. Both differences are flagged: the changed line, and the link to a different host.

No setup is needed. The Templates tab lists every template with when it was last seen and last changed, and its history: the newest comparison on Free, the last 20 comparisons on Starter and up.

What it does not see:

  • A change in layout or styling only (CSS, colours, spacing: no text, link or image change and less than 30 % size change).
  • A changed subject starts a new template instead of showing as a change. A subject with changing words in it (a product name, a person's name not in the To header) makes one template per value.
  • Click-tracking links hide the real destination, so all such links look alike.

How it compares:

  • Text line by line, link and image addresses (host and path; query values and ids masked), attachments, and a size change over 30 %.
  • Per-recipient values are masked before anything is compared: email addresses, URLs, codes the message carries, numbers, amounts, dates, times, ids and tokens, the recipient's name (from the To header, a first.last address and the word after "Hi", "Dear", ...).
  • Parts that turn out to change from email to email (an order's items, a comment someone wrote) are learnt and then ignored. With only one earlier email nothing is learnt yet, so the second email of such a template may show differences: they are marked as a first comparison and not flagged in the inbox list.
  • Only masked content is kept (no addresses, names or codes), for the last 500 templates per environment. In main, a message belongs to the template history of the environment it was sent to.

Routing rules

Account admins keep rules on main's Rules tab, on every plan (Free 1 rule, Starter 3, Team 20, Business 50; see /pricing; if a plan shrinks, every rule is kept and the oldest ones stay in force). Each new message of the account is checked against them top to bottom and the first rule that matches decides:

  • When: recipient address (*billing*@*; * = anything, ? = one character, also matched on the "intended for" address of the full-original form), sender (*@stripe.com), subject contains a text or matches a regular expression, has or has no attachment. Every condition you fill in must match.
  • Then: also show it in another environment (it stays where its address puts it, and in main), give it a tag (shown in the inbox, with a tag filter), mark it important (a pinned badge, with an "Important only" filter), and/or notify one or more of the account's notification destinations (see Notifications).
  • Rules never deliver or forward mail and never show it outside your account. A message is judged once, within about a minute of arriving (at once when someone opens or waits on the inbox); changing a rule affects new mail only.
  • In the environment it was routed to, a message is listed, waited for (/v1/messages/wait), read and downloaded like its own mail, inside that environment's retention; it is still deleted when the retention period of the environment it was sent to ends. Deleting it there only hides it there; deleting it where it was sent (or in main) deletes it everywhere.

Notifications

Account admins add destinations on main's Notifications tab: a Slack channel (incoming webhook), a Microsoft Teams channel (Workflows webhook), a Discord channel, a Google Chat space, a PagerDuty service (Events API v2 integration key) or your own HTTPS webhook. Free has 1 destination, Starter 2, Team 5, Business 20 (/pricing; if a plan shrinks, nothing is deleted and the oldest ones stay on). Each destination is for all environments or for one, has a lowest severity (Info, Success, Warning, Error) and receives the events you tick:

  • New mail (mail.received): one per new message, within about a minute of arriving.
  • Email check failed (mail.qa_failed, Warning) and Template changed (template.changed).
  • Usage limits (usage.threshold): 80 % (Warning) and 100 % (Error) of the month's messages, the daily limit reached, rate limited; each at most once per month or day.
  • Account and billing: trial ending (3 days and 1 day before), payment failed, plan changed.
  • Own domains verified or not verified, and SMTP catcher logins locked after repeated failures.
  • Routing rules: a rule's Notify action sends routing.rule.<id> to the destinations it names, on every plan within the plan's rule count.

A destination gets at most one post a minute; more events in that minute arrive as one summary. Send test posts a test card at once and shows the result; Deliveries lists the last 30 days. A destination that keeps failing (the webhook was removed, the key revoked) is turned off with the reason shown; fix it and turn it on again.

Privacy: a notification carries the masked subject (codes, numbers, addresses and links replaced by {n}, {email}, {url}), the sender's and "intended for" domains, sizes and counts, and a link into this app: never a full email address, a message body, a code or a link from the mail. Destinations (webhook URLs, keys, signing secrets) are stored encrypted by our notification service, never by this app, and shown masked.

Webhooks receive signed JSON: {"type":"notificationcentral.delivery","version":1,"deliveryId":"...","test":false,"events":[...]} with the header NotificationCentral-Signature: t=<unix seconds>,v1=<hex>. Check it before you trust the body: HMAC-SHA256 with your signing secret over <t>. plus the raw body, lower-case hex, compared with v1 in constant time, and t within 5 minutes of your clock. The secret is shown once when you add the webhook (and on request).

Usage

The Usage tab shows the last 30 days: messages received per day (in main stacked by environment), messages refused per day by reason (quota, plan, rate; size once MailPier reports it), this month against the quota (during the 14-day Team trial, up to 5,000 messages, no card needed: the trial's messages against its 5,000, which are for the whole trial), today against the daily limit, API requests per day per key (managers), the top 10 sender domains and the top 10 templates. Every chart has a table view and the page has a CSV download.

Service status

Current status and the last 90 days of receiving mail, the web app and API, the SMTP catcher and the mail processing delay: mailpier.io/status.

SMTP catcher

Change only a test app's SMTP settings to smtp.mailpier.io (587 or 2525 with STARTTLS, 465 with TLS) and log in with the environment's SMTP user name and a password from its SMTP tab: everything the app sends is caught in that environment, whatever the recipient, and never delivered. Every plan, Free included, within the plan's message limits. Setup guide with copy-paste settings for .NET, Node, Python, Java, PHP and WordPress.

Leaving, deleting your login, deleting the account

  • Leave an environment or a whole account, or delete your login, on Your login (the email address at the top right). The last account admin of an account must first delete it or add another account admin.
  • Delete the account: an account admin, on main's Settings, under "Delete this account". Mail is refused and nobody can sign in from that moment, a paid plan is cancelled at once (no refund, see the Terms), and after 7 days everything is deleted for good. Until then any account admin can restore it from the link in the email we send, or from the accounts page.
  • Only want to stop paying? Cancel under Manage billing instead: the account moves to the Free plan at the end of the paid period and nothing is deleted. Free accounts nobody uses for 12 months (no sign-in, no mail) are closed after two email warnings.

curl

# a fresh address for this test run
curl -s -X POST https://api.mailpier.io/v1/addresses -H "Authorization: Bearer $MPI_KEY"
# => {"address":"k3v9q2mz7a@qa.acme.mailpier.io", ...}

# wait up to 60 s for the mail and print it (204 = nothing arrived)
curl -s "https://api.mailpier.io/v1/messages/wait?to=k3v9q2mz7a@qa.acme.mailpier.io&timeoutSeconds=60" \
     -H "Authorization: Bearer $MPI_KEY"

.NET (NuGet package MailPier.Inbox.Client)

dotnet add package MailPier.Inbox.Client

using MailPier.Inbox.Client;

var inbox = new MailPierInboxClient(Environment.GetEnvironmentVariable("MPI_KEY")!);
var address = await inbox.NewAddressAsync();               // k3v9q2mz7a@qa.acme.mailpier.io
var started = DateTimeOffset.UtcNow;

await myApp.SignUpAsync(address);                           // your code sends the mail

var mail = await inbox.WaitForMessageAsync(address, TimeSpan.FromSeconds(60),
                                           subjectContains: "Confirm", since: started);
var code = mail.Codes.FirstOrDefault();                     // "482913"
var link = mail.FirstLink("confirm");                       // https://...
await inbox.DeleteAsync(mail.Id);

Node.js, Playwright and Cypress (npm package @mailpier/inbox)

npm install --save-dev @mailpier/inbox

import { MailPierInbox } from "@mailpier/inbox";

const inbox = new MailPierInbox({ apiKey: process.env.MAILPIER_API_KEY });
const address = await inbox.newAddress({ prefix: "signup" }); // signup-k3v9q2mz7a@qa.acme.mailpier.io

await myApp.signUp(address);                                  // your code sends the mail

const mail = await inbox.waitForMessage({ to: address, subjectContains: "Confirm", timeoutMs: 60_000 });
const code = mail.code;                                       // "482913"
const link = mail.firstLink("confirm");                       // https://...

Playwright: import test from @mailpier/inbox/playwright and every test gets an inbox fixture (await inbox.waitForCode(email), await inbox.waitForLink(email, "verify")). Cypress: register mailpierTasks() in setupNodeEvents, import @mailpier/inbox/cypress/commands in your support file and use cy.mailpierNewAddress() and cy.mailpierWaitForCode(email); the API key stays in the Cypress Node process. TypeScript types, ESM and CommonJS, Node 18+. Full reference on npm.

Python and pytest (PyPI package mailpier-inbox)

pip install mailpier-inbox

from mailpier_inbox import MailPierInbox

inbox = MailPierInbox()                                       # key from MAILPIER_API_KEY
address = inbox.new_address(prefix="signup")                  # signup-k3v9q2mz7a@qa.acme.mailpier.io

my_app.sign_up(address)                                       # your code sends the mail

mail = inbox.wait_for_message(address, subject_contains="Confirm", timeout=60)
code = mail.code                                              # "482913"
link = mail.first_link("confirm")                             # https://...

# pytest: the fixture comes with the package
def test_sign_up(mailpier_inbox, page):
    email = mailpier_inbox.new_address()
    page.fill("#email", email); page.click("text=Create account")
    page.fill("#code", mailpier_inbox.wait_for_code(email))

Installing the package registers a pytest plugin with the mailpier_inbox fixture; @pytest.mark.mailpier_cleanup (or pytest --mailpier-cleanup) deletes the test's mail afterwards. Python 3.9+. Full reference on PyPI.

Azure DevOps pipeline task

Install the MailPier Inbox extension from the Visual Studio Marketplace in your organisation, add a secret pipeline variable with your API key, then:

- task: MailPierInboxWait@1
  inputs:
    apiKey: '$(MailPierInboxKey)'           # secret variable
    address: 'signup-$(Build.BuildId)@qa.acme.mailpier.io'
    subjectContains: 'Confirm'
    timeoutSeconds: '120'
- script: dotnet test --filter ConfirmSignup   # reads MPI_CODE / MPI_LINK
  env:
    MPI_CODE: $(MailPierInbox.Code)             # secret: map it into env explicitly
    MPI_LINK: $(MailPierInbox.Link)

The task fails the step when no mail arrives in time. It sets MailPierInbox.Code, MailPierInbox.Link and MailPierInbox.MessageId for the following steps; the code and the link are secret variables (masked, never printed), so map them into env:.

GitHub Actions

Use the MailPier Inbox wait action (mailpier/inbox-wait-action@v0) with your API key in a repository secret:

- uses: mailpier/inbox-wait-action@v0
  id: mail
  with:
    api-key: ${{ secrets.MAILPIER_API_KEY }}
    to: signup-${{ github.run_id }}@qa.acme.mailpier.io
    subject-contains: Confirm
    timeout: 180
- run: ./confirm-account.sh "${{ steps.mail.outputs.code }}" "${{ steps.mail.outputs.first-link }}"

The step fails when no mail arrives in time (fail-on-timeout: false carries on with timed-out = true). It outputs code, first-link, message-id, subject, from and received-utc; the API key is masked in the log.

API reference

Base URL https://api.mailpier.io, header Authorization: Bearer mpi_..., JSON.

CallWhat it does
GET /v1/meAccount (with its plan in force), environment, domains, this month's usage and quota (per account).
POST /v1/addressesA fresh random address of the key's environment. Optional body {"domain":"...","prefix":"signup"}.
GET /v1/messages?to=&subject=&since=&afterId=&take=50&skip=0Newest first, as {"items":[...],"skip":0,"take":50} (take up to 100). to = exact address, subject = contains, since = ISO 8601. hasAttachments in a list is a best guess for mails over 16 KiB; the single-message call is exact.
GET /v1/messages/wait?to=&subject=&since=&timeoutSeconds=30Long-poll (max 120 s): 200 with the oldest matching mail after since, or 204 on timeout. To wait for the NEXT mail after one you have, pass since = its receivedUtc and afterId = its id (mail stored in the same millisecond is not missed).
GET /v1/messages/{id}Text, HTML (as received), headers, links, codes, attachments, auth and spam verdicts, and the email check report qa (also on wait).
POST /v1/messages/{id}/check-linksChecks every web link of the message: {"status","checkedUtc","total","checked","links":[{"url","outcome","status","finalUrl","hops","detail"}]}; outcome ok, broken, blocked, error or timeout. 429 over the plan's link check limit (Free per month, the other plans per hour).
GET /v1/messages/{id}/rawThe original .eml.
GET /v1/messages/{id}/attachments/{index}One attachment.
DELETE /v1/messages/{id}Deletes one mail (204).
DELETE /v1/messages?to=Deletes all mail to one address; returns {"deleted":n,"skippedShared":m} (a mail also sent outside your environment is left to expire).

Errors are {"error":"..."} with 400, 401 (key), 403 (account suspended), 404, 429 (rate limit per key: your plan's API rate, see /pricing and Retry-After) or 503.

Guides

Step-by-step articles on testing the email your software sends: email testing guides on the Solutions Group Unlimited website.

An unhandled error has occurred. Reload X