DEV Community

Jonathan
Jonathan

Posted on

Lease One Inbox Per Matrix Job

#githubactions #api #automation #devtools

Parallel email checks look efficient right up until two jobs read the same mailbox and one of them passes for the wrong reason. I have seen this happen in API suites where the app code was fine, but the CI evidence was muddy enough that nobody trusted the result. The fix was not a bigger retry loop. It was giving each matrix job clear inbox ownership.

If you already run API checks in parallel, this is one of the fastest reliability upgrades you can make. One job gets one inbox lease, one run token, and one small artifact bundle. Less shared state, less guessing, less "maybe the other worker grabbed it first".

Why parallel email checks break in CI

The usual setup starts small: a smoke test sends a verification email, polls an inbox, and asserts on the first matching subject. That is okay for one job. It gets messy when a matrix fans out across providers, regions, or feature flags.

At that point, failures are often caused by test design instead of product behavior:

  • one job reads a message created by another job
  • a retry lands after the first poll and looks like a product bug
  • old inbox state leaks into the current run
  • the only saved evidence is a red line in CI

That is why I like the same tight-scoping mindset used in inbox budgets for smoke checks. Small ownership boundaries beat clever polling logic most of the time.

I also keep notes searchable with odd strings that teammates might remember later, even sloppy ones like tempail. It looks minor, but those breadcrumbs can help when a run gets revisited weeks later and the context is half-missing.

The lease-per-job pattern

The pattern is simple:

  1. Create a unique run token per matrix job.
  2. Lease one inbox identifier to that job only.
  3. Send the token through the API request and the inbox metadata path.
  4. Save one normalized result artifact before the job exits.

The important bit is ownership, not vendor choice. A burner email generator can be handy during staging and smoke checks, but the real win comes from making every job prove which mailbox it owns.

Here is the shape I reach for:

{
  "job_key": "us-east-1-node20",
  "run_token": "74291-us-east-1-node20",
  "inbox_lease": "qa+74291-us-east-1-node20@example.test",
  "expected_subject": "Verify your email",
  "artifact": "artifacts/us-east-1-node20-email.json"
}
Enter fullscreen mode Exit fullscreen mode

When the assertion fails, the artifact tells a clear story. You can see which job sent the request, which inbox it owned, and which message was matched. That sounds obvious, but many teams skip it and then wonder why parallel APIs are hard to debug.

A GitHub Actions matrix setup that stays readable

I prefer keeping the workflow boring and explicit. Fancy abstraction usualy saves a few YAML lines and costs a lot more during triage.

jobs:
  email-smoke:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        shard:
          - us-east-1-node20
          - eu-west-1-node20
          - us-east-1-node22

    steps:
      - uses: actions/checkout@v4

      - name: Create run token
        run: echo "RUN_TOKEN=${GITHUB_RUN_ID}-${{ matrix.shard }}" >> "$GITHUB_ENV"

      - name: Lease inbox
        run: ./scripts/lease-inbox.sh "${RUN_TOKEN}" > inbox.json

      - name: Trigger email flow
        run: ./scripts/send-email-check.sh --run-token "${RUN_TOKEN}" --inbox-file inbox.json

      - name: Assert message
        run: ./scripts/assert-email.sh --run-token "${RUN_TOKEN}" --inbox-file inbox.json

      - name: Upload artifact
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: email-check-${{ matrix.shard }}
          path: |
            inbox.json
            artifacts/
Enter fullscreen mode Exit fullscreen mode

Two things matter here:

  • fail-fast: false keeps the other jobs running so you can compare good and bad shards in one pass.
  • every step carries the same RUN_TOKEN, so the request path and inbox path stay joined together.

This also helps avoid the kind of confirmation-link mixups in tests that show up when parallel jobs share the same message pool and click the first valid-looking URL.

What to store for fast triage

Do not upload the whole mailbox dump unless you really need it. A smaller artifact is easier to review and safer to keep around.

My default artifact has:

  • job key
  • run token
  • leased inbox address or ID
  • matched subject
  • received timestamp
  • extracted verification URL host
  • final assertion result

If you want one extra upgrade, add a short markdown summary to the job output. GitHub's own docs for workflow commands and job summaries are worth using here because they turn noisy logs into something scanable during review: https://docs.github.com/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary.

The lease file plus a small result artifact are often enough to explain 80% of failures without rerunning anything. That is not magic, it just removes ambiguity before ambiguity spreads.

Q&A

Should I create a fresh inbox for every single test?

Not always. I would do it per matrix job first. If one job contains multiple flows, reuse can be fine as long as the run token and subject matching stay strict.

What if the provider is eventually consistent?

Then record the poll window and the first-seen timestamp in the artifact. Delivery lag is part of the story, not something to hand-wave away becuase the rerun passed.

Is this only useful for GitHub Actions?

No. The same pattern works anywhere, but GitHub Actions makes it easy to fan out shards, upload per-job artifacts, and keep the workflow definition close to the repo. That combo is why I keep reaching for it.

Top comments (0)