GitHub Actions

ZeroDrop has a native GitHub Action that generates a disposable inbox before your tests run and injects it as an environment variable.

Basic usage

name: E2E Tests

on: [push, pull_request]

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

      - name: Generate test inbox
        id: inbox
        uses: zerodrop-dev/setup-zerodrop@aa882ace46b204bfd84bbcc374df73d32cf67343 # v1.1.0

      - name: Run Playwright tests
        run: npx playwright test
        env:
          TEST_INBOX: ${{ steps.inbox.outputs.inbox }}

Accessing the inbox in tests

import { ZeroDrop } from 'zerodrop-client';

const mail = new ZeroDrop();

// Uses CI inbox if available, generates one locally otherwise
const inbox = process.env.TEST_INBOX ?? mail.generateInbox();

Private inboxes with a free API key

Without a key, anyone who knows an inbox’s name can read it, and one sender can reach only 5 different inboxes a day: past that, the inbox gets a notice from notice@zerodrop.dev instead of the email. Sign in with GitHub at zerodrop.dev/keys for a free key, save it as the repository secret ZERODROP_API_KEY, and pass it to the action:

- name: Generate test inbox
  id: inbox
  uses: zerodrop-dev/setup-zerodrop@aa882ace46b204bfd84bbcc374df73d32cf67343 # v1.1.0
  with:
    api-key: ${{ secrets.ZERODROP_API_KEY }}

With v1.1.0 or later, the inbox name starts with your key’s prefix (k7x2-swift-x7k2m@zerodrop-sandbox.online), only your key can read it, and mail to it isn’t limited. The action exports ZERODROP_API_KEY to the steps that follow, where the SDKs pick it up on their own (TypeScript 0.3.0+; Python, Ruby, Go, PHP and Java 0.2.0+). If the job already sets ZERODROP_API_KEY in its env, the action uses that key and you can leave out api-key.

SHA pinning (recommended)

Pin to a specific commit SHA for supply chain security:

# Recommended — pin to SHA
uses: zerodrop-dev/setup-zerodrop@aa882ace46b204bfd84bbcc374df73d32cf67343 # v1.1.0

# Not recommended — floating tag
uses: zerodrop-dev/setup-zerodrop@v1

Parallel matrix builds

Each matrix job gets its own isolated inbox automatically:

jobs:
  test:
    strategy:
      matrix:
        browser: [chromium, firefox, webkit]
    steps:
      - name: Generate test inbox
        id: inbox
        uses: zerodrop-dev/setup-zerodrop@aa882ace46b204bfd84bbcc374df73d32cf67343 # v1.1.0

      - name: Run tests
        run: npx playwright test --project=${{ matrix.browser }}
        env:
          TEST_INBOX: ${{ steps.inbox.outputs.inbox }}

Each browser gets a different inbox — no collisions between parallel jobs.

Full workflow example

name: E2E Tests

on:
  push:
    branches: [main]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Install Playwright browsers
        run: npx playwright install --with-deps chromium

      - name: Generate test inbox
        id: inbox
        uses: zerodrop-dev/setup-zerodrop@aa882ace46b204bfd84bbcc374df73d32cf67343 # v1.1.0

      - name: Run E2E tests
        run: npx playwright test
        env:
          TEST_INBOX: ${{ steps.inbox.outputs.inbox }}
          BASE_URL: ${{ secrets.STAGING_URL }}

      - name: Upload test results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: playwright-report
          path: playwright-report/

Action outputs

Output	Description	Example
`inbox`	Full email address	`swift-x7k2m@zerodrop-sandbox.online`, or `k7x2-swift-x7k2m@…` with an API key
`name`	Inbox name only	`swift-x7k2m`

Security

The Action generates inbox names locally on the runner — no network request is made during generation. The inbox address is a random string; it does not contact ZeroDrop servers until your tests begin polling. See SECURITY.md for full supply chain documentation.

Getting Started

SDKs

Frameworks

CI/CD

Reference

GitHub Actions

GitHub Actions

Basic usage

Accessing the inbox in tests

Private inboxes with a free API key

SHA pinning (recommended)

Parallel matrix builds

Full workflow example

Action outputs

Security

​GitHub Actions

​Basic usage

​Accessing the inbox in tests

​Private inboxes with a free API key

​SHA pinning (recommended)

​Parallel matrix builds

​Full workflow example

​Action outputs

​Security

GitHub Actions

Basic usage

Accessing the inbox in tests

Private inboxes with a free API key

SHA pinning (recommended)

Parallel matrix builds

Full workflow example

Action outputs

Security