Complete Guide: Automated Email Testing in GitHub Actions

Why Test Emails in CI?

Signup confirmations, password resets, invitation emails — many web applications depend on email delivery. Yet few teams automatically test these flows in CI.

The reason is clear: CI runners have no way to receive emails.

MailBrew is an API-based email receiving service. It lets you receive and verify emails from CI environments with just a few lines of code.

Architecture

GitHub Actions Runner
  → Application (test SMTP: smtp.mailbrew.io:587)
  → MailBrew API (wait for & retrieve emails)
  → Test assertions

Simply point your application's SMTP settings to MailBrew, and retrieve sent emails via the API.

Setup

1. Configure API Key

Add MAILBREW_API_KEY to your repository's Settings > Secrets.

2. Workflow File

name: E2E Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies
        run: npm ci

      - name: Run E2E tests
        run: npx playwright test
        env:
          MAILBREW_API_KEY: ${{ secrets.MAILBREW_API_KEY }}
          SMTP_HOST: smtp.mailbrew.io
          SMTP_PORT: 587

3. Test Code

import MailBrew from '@mailbrew/sdk';

const mb = new MailBrew(process.env.MAILBREW_API_KEY);

// Create a test address
const addr = await mb.addresses.create({ ttl: 300 });

// Sign up via the application
await signupUser(addr.address, 'password123');

// Wait for confirmation email (up to 30s)
const emails = await mb.addresses.waitForEmail(addr.address, {
  timeout: 30,
  count: 1,
});

// Assert
expect(emails[0].subject).toContain('Confirm your email');
expect(emails[0].html_body).toContain('Confirm');

SDK Examples

Python

from brewmail import MailBrew

mb = MailBrew(os.environ['MAILBREW_API_KEY'])
addr = mb.addresses.create(ttl=300)

trigger_signup(addr.address)

emails = mb.addresses.wait_for_email(addr.address, timeout=30)
assert 'Confirm your email' in emails[0].subject

PHP

use BrewMail\MailBrew;

$mb = new MailBrew(env('MAILBREW_API_KEY'));
$addr = $mb->addresses()->create(['ttl' => 300]);

$emails = $mb->addresses()->waitForEmail($addr->address, ['timeout' => 30]);
$this->assertStringContains('Confirm', $emails[0]->subject);

Best Practices

1. Use short TTLs — 5 minutes (300 seconds) is enough for test addresses
2. Set explicit timeouts — 30 seconds for waitForEmail is recommended
3. Use unique addresses per test — Prevents conflicts during parallel execution
4. Use the assertion API — POST /assert validates subject, body, and recipients in one call

Summary

Email auth flow testing in CI is no longer "nice to have but impossible." With MailBrew, you can integrate it into your existing CI/CD pipeline in minutes.

Get started free →