Home / Guides / Test emails in an Azure DevOps pipeline
Test emails in an Azure DevOps pipeline: wait for a mail and use its code or link in the next step
A pipeline test signs up a user, and the app sends a confirmation email with a one-time code or a link. The next step needs that code. This guide shows the free way to do it in Azure Pipelines with a Mailpit service container and a short PowerShell step, how to hand the code to the next step without printing it in the log, and where this approach stops.
Short answer.
Run Mailpit as a service container in the job, point the app under test at localhost:1025, and add a
PowerShell step that polls Mailpit's API on port 8025 until a message to the test's address arrives. That step pulls out the code
and sets it as a secret pipeline variable with ##vso[task.setvariable ...;issecret=true]. The next step
maps it into env: and uses it. When the email comes from an already deployed test system, a hosted test inbox such as
MailPier Inbox receives it instead, and its Azure DevOps task does the waiting.
The free way: Mailpit as a service container
Mailpit is a free, open-source mail catcher: an SMTP server on port 1025 and a web inbox and REST API on port 8025. It accepts every message and delivers none. Azure Pipelines can start it for you as a service container: the agent pulls the image, starts it before the job's steps and removes it when the job ends. Only YAML pipelines support service containers, and the Mailpit image is a Linux image, so use the Microsoft-hosted Ubuntu pool (or a self-hosted Linux agent with Docker). The hosted Windows pool runs Windows containers only, and the hosted macOS pool runs no containers.
The job below runs directly on the agent, not in a container, so the service is reached on localhost and the ports must
be mapped:
# azure-pipelines.yml
pool:
vmImage: ubuntu-latest
resources:
containers:
- container: mailpit
image: axllent/mailpit:latest
ports:
- 1025:1025 # SMTP: the app under test sends here
- 8025:8025 # web inbox and REST API: the test reads here
services:
mailpit: mailpit
steps:
# ... checkout, build, start the app under test with SMTP = localhost:1025 ...
In a pipeline you rely on, replace latest with a fixed Mailpit version tag, so a new release cannot change a build
without a commit. Configure only the test settings of your app: SMTP host localhost, port 1025, no TLS, no login. If the app
itself runs in a container job, leave out ports and use the host name mailpit, because containers on the
same job network reach each other by their service name.
Step 1 and 2: a unique address, then trigger the email
Every run gets its own address, so a retried job or a parallel run never reads someone else's mail. A variable set with
task.setvariable is available to the later steps of the job, not the step that sets it:
- pwsh: |
$address = 'signup-{0}@example.test' -f [guid]::NewGuid().ToString('N').Substring(0, 8)
Write-Host "##vso[task.setvariable variable=TestAddress]$address"
displayName: Pick a unique test address
# Your own step that makes the app send the email, for example an end-to-end test that signs up:
- pwsh: ./tests/Start-SignUp.ps1 -Email $env:TEST_ADDRESS
displayName: Sign up (the app sends the email)
env:
TEST_ADDRESS: $(TestAddress)
Step 3: wait for the email and take the code
Two Mailpit API calls do the work: GET /api/v1/search?query=to:"address" finds messages (newest first) and
GET /api/v1/message/{ID} returns one with its text and HTML parts already decoded. The step polls with a deadline,
fails the job with a clear error when nothing arrives, and sets the code and the link as secret variables:
- pwsh: |
$to = $env:TEST_ADDRESS
$api = 'http://localhost:8025/api/v1'
$search = "$api/search?limit=50&query=" + [uri]::EscapeDataString('to:"' + $to + '"')
$deadline = (Get-Date).AddSeconds(60)
$mail = $null
while (-not $mail -and (Get-Date) -lt $deadline) {
try {
# Newest first. to: also matches longer addresses that contain $to, so check the exact address.
$hit = (Invoke-RestMethod -Uri $search).messages |
Where-Object { @($_.To | ForEach-Object { $_.Address }) -contains $to } |
Select-Object -First 1
if ($hit) { $mail = Invoke-RestMethod -Uri "$api/message/$($hit.ID)" }
} catch { } # Mailpit may still be starting
if (-not $mail) { Start-Sleep -Milliseconds 500 }
}
if (-not $mail) {
Write-Host "##vso[task.logissue type=error]No email to $to arrived within 60 seconds."
exit 1
}
$m = [regex]::Match([string]$mail.Text, '(?i)code is (\d{6})')
if (-not $m.Success) { Write-Host '##vso[task.logissue type=error]No code found in the email.'; exit 1 }
$link = [regex]::Matches([string]$mail.HTML, 'href\s*=\s*"([^"]+)"') |
ForEach-Object { [System.Net.WebUtility]::HtmlDecode($_.Groups[1].Value) } |
Where-Object { $_ -like '*/verify*' } | Select-Object -First 1
Write-Host "##vso[task.setvariable variable=EmailCode;issecret=true]$($m.Groups[1].Value)"
Write-Host "##vso[task.setvariable variable=EmailLink;issecret=true]$link"
displayName: Wait for the email in Mailpit
env:
TEST_ADDRESS: $(TestAddress)
Step 4: use the code in the next step
Secret variables are masked in the log and are not put into the environment of later steps automatically. Map them
explicitly with env:, and pass them as environment variables, never on a command line:
- pwsh: ./tests/Confirm-SignUp.ps1 -Email $env:TEST_ADDRESS -Code $env:EMAIL_CODE
displayName: Confirm the sign-up with the code
env:
TEST_ADDRESS: $(TestAddress)
EMAIL_CODE: $(EmailCode) # secret: only reaches the script through env
Pitfalls in pipelines
- Poll with a deadline, never a fixed sleep. Hosted agents vary in speed, and the app may queue or retry its mail. A
fixed
Start-Sleep 10is either too short on a slow agent or wastes time on every run. - Mailpit may still be starting. The first API call can fail while the container comes up, which is why the loop above catches errors and tries again until the deadline.
- Match the exact address. Mailpit's
to:filter also matches a longer address that contains yours, so the script compares the address in the results. - Match the code by its wording.
\b\d{6}\balso matches an order number. Anchor the pattern to the template text, for example(?i)code is (\d{6}). - Do not echo the code. A one-time code or a sign-in link is a credential for that test account. Set it with
issecret=trueso the log shows***.
For the same polling in a Playwright or Node.js test, and more on HTML links and quoted-printable bodies, see Read a verification code or magic link from an email in an automated test.
Where a service container stops
Mailpit in the job works when the job starts the app itself. It does not help when:
- The pipeline tests a deployed system. A release stage that runs smoke tests against a test or staging server cannot
point that server's SMTP at
localhoston a build agent. The server sends through its own mail server, and the agent never sees the message. - The job runs on a Windows or macOS agent. The Linux image cannot run there, so the job has to install and start a mail catcher itself, or the test moves to an Ubuntu job.
- Several pipelines and testers need the same mail. A shared catcher for a test environment means someone hosts it, secures its inbox and API and keeps it running.
A hosted test inbox with a pipeline task
MailPier Inbox receives the mail on the internet instead of on the agent. Each account has addresses such as
anything@qa.acme.mailpier.io for its qa environment, so a deployed test system can send to them like to any other
address. Its free extension on the Visual Studio Marketplace adds the task MailPierInboxWait@1. It waits for a mail to
the address (up to the timeout you set, 120 seconds by default), fails the step when nothing arrives, and sets the first one-time code and
the first link as secret variables. There is no script and no regular expression to maintain:
- task: MailPierInboxWait@1
displayName: Wait for the sign-up email
inputs:
apiKey: '$(MailPierInboxKey)' # secret pipeline variable
address: 'signup-$(Build.BuildId)@qa.acme.mailpier.io'
subjectContains: 'Confirm'
timeoutSeconds: '120'
- pwsh: ./tests/Confirm-SignUp.ps1 -Code $env:EMAIL_CODE -Link $env:EMAIL_LINK
env:
EMAIL_CODE: $(MailPierInbox.Code) # secret variables set by the task
EMAIL_LINK: $(MailPierInbox.Link)
Store the API key as a secret pipeline variable (here MailPierInboxKey). The task also has inputs for an address held in a
variable set by an earlier step, and for ignoring mail received before a given time. The task needs agent version 3.232.1 or later, which
Microsoft-hosted agents already have.
Questions
How do I test emails in an Azure DevOps pipeline?
Run a mail catcher such as Mailpit as a service container in the job, point the app under test at its SMTP port, and add a step that polls the catcher's API until the email to the test's own address arrives. That step takes the code or link out of the message and sets it as a secret pipeline variable for the next step.
How do I pass a value from one pipeline step to the next?
Write the logging command ##vso[task.setvariable variable=Name]value to standard output. Later steps in the same job can use $(Name). Add issecret=true for codes and links: the value is then masked in the log and reaches a script only when you map it into the step's env: section.
Can I use a Mailpit service container on a Windows build agent?
Not the Linux Mailpit image. Microsoft-hosted Windows agents run Windows containers only, and macOS agents run no containers. Run the email test in an Ubuntu job, or install and start a mail catcher in the job yourself.
Why can't my pipeline see the email a deployed staging server sends?
Because the staging server sends through its own mail server, not to localhost on the build agent. A catcher inside the job only sees mail from an app the job runs itself. For a deployed system you need a catcher hosted for that environment, or a hosted test inbox such as MailPier Inbox.
Is there an Azure DevOps task that waits for an email?
Yes. The free MailPier Inbox extension on the Visual Studio Marketplace adds the task MailPierInboxWait@1. It waits for a mail to a MailPier Inbox address, fails the step when nothing arrives in time, and sets the first code and link as the secret variables MailPierInbox.Code and MailPierInbox.Link. It needs a MailPier Inbox account; a new account starts with a 14-day Team trial, up to 5,000 messages, no card needed.
Related
- Read a verification code or magic link from an email in an automated test
- MailPier Inbox: test inboxes for QA and dev teams
- All guides
Sources: Service containers, Set variables in scripts, Set secret variables, Logging commands, Mailpit API v1, Mailpit Docker images, MailPier Inbox extension, MailPier Inbox Azure DevOps task docs.