Quick start

Every workspace receives mail at anything.<workspace>@inbox.mailpier.io. The part before the last dot is yours to choose, so give each test its own address. Mail is kept for the workspace's retention period (12 hours by default), then deleted.

1. Open your workspace, go to API keys and create a key. It is shown once; store it as a secret.
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.

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.yourteam@inbox.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.yourteam@inbox.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.yourteam@inbox.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);

Azure DevOps pipeline task

Install the MailPier Inbox extension 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).yourteam@inbox.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:.

API reference

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

Call	What it does
GET /v1/me	Workspace, domains, this month's usage and quota.
POST /v1/addresses	A fresh random address. Optional body {"domain":"...","prefix":"signup"}.
GET /v1/messages?to=&subject=&since=&afterId=&take=50&skip=0	Newest 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=30	Long-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.
GET /v1/messages/{id}/raw	The 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 workspace is left to expire).

Errors are {"error":"..."} with 400, 401 (key), 403 (workspace suspended), 404, 429 (rate limit, see Retry-After) or 503.