Local Inbox Contracts Before CI

I like catching email regressions before a pull request burns ten minutes of CI. For teams that ship a lot of signup, invite, or reset flows, the cheapest win is often a tiny local inbox contract. It gives developers one repeatable way to prove, "this build triggered the right message with the right link," before the wider pipeline even starts.

That sounds small, but it changes the feel of the workflow. Instead of treating email as a mysterious thing that only CI can validate, you make it part of normal development. The result is faster feedback, fewer flaky reruns, and much less shared-inbox chaos. That is realy the main win.

Why local inbox contracts beat waiting for CI

CI is still the place where release confidence gets recorded. I am not arguing against that. I am arguing against discovering every email bug there first.

When developers can run the same inbox check locally, two useful things happen:

• they fix broken subjects, bad links, and stale templates earlier
• they learn what the system actually promises, not just what the UI hopes happens

That second point matters a lot. A good contract is not "some email arrived." A good contract says which scenario triggered it, what link path should exist, and what small fields are safe to assert. That is very close to the same mental model behind stable resend attempts in UI flows: define identity first, then let retries behave around it.

I have seen teams skip this because they assume local inbox tooling will be messy. Honestly, it does not have to be. A plain markdown note or JSON file per scenario is enough to start, and it keeps the whole thing surprizingly grounded.

What belongs in the contract

My rule is simple: the contract should be boring enough that any developer can read it in thirty seconds.

For a signup or invite flow, I usually keep:

• scenario name
• trigger command or API route
• expected subject fragment
• expected link path
• timeout budget
• one isolated inbox alias

That is it. If you add too many fields, the contract turns into documentation nobody updates. If you add too few, failures become vague and everybody starts guessing. Keep it smalll and specific.

Here is a small version:

{
  "scenario": "trial-signup",
  "trigger": "pnpm smoke:trial-email",
  "subject_contains": "Start your free trial",
  "path_contains": "/activate",
  "timeout_seconds": 45,
  "inbox_alias": "trial-signup-ci"
}

I also like storing one line of evidence after each run: message id, resolved URL, and timestamp. Not the full body, not a massive artifact bundle, just enough to explain what happend. That tiny receipt is usualy more valuable than another screenshot.

A small implementation that teams can keep

The easiest setup is to keep the contract file in the repo and let one script read it.

#!/usr/bin/env bash
set -euo pipefail

contract="${1:?usage: smoke-email <contract.json>}"
scenario="$(jq -r '.scenario' "$contract")"
trigger="$(jq -r '.trigger' "$contract")"
subject="$(jq -r '.subject_contains' "$contract")"
path="$(jq -r '.path_contains' "$contract")"
timeout="$(jq -r '.timeout_seconds' "$contract")"

eval "$trigger"
./wait-for-email \
  --scenario "$scenario" \
  --subject "$subject" \
  --path "$path" \
  --timeout "$timeout"

There are prettier ways to do it, sure, but this form is easy to reason about. It also gives frontend and backend folks one shared object to discuss. If somebody changes the redirect path or the email subject, the contract changes with it. That keeps local checks aligned with CI instead of drifting apart a week later.

This is also where isolated scenarios matter. A lot of "email testing is flaky" complaints are really routing problems. One inbox alias per scenario keeps things readable, and it borrows the same lesson as separating email change checks by scenario: do not make humans untangle mixed evidence after the fact.

Where free disposable email fits

For local smoke tests, I think free disposable email can be genuinely useful when it stays inside a clear workflow. The goal is not to bolt random inboxes onto every test. The goal is to give developers a cheap, resettable place to validate delivery behavior without touching real accounts.

That is where tools like tempmailso often enter the conversation. I would still treat the provider as an implementation detail. What matters more is whether the inbox is scriptable, isolated per scenario, and easy to rotate when a test starts collecting junk like temp gamil com from exploratory input.

In other words: good Developer Tools habits matter more than brand loyalty. A provider can help you receive the message, but the contract is what makes the signal useful.

Quick Q&A

Should every developer run inbox checks locally?

Not every time. I would use them for flows where email is the product boundary: signup, password reset, invites, and trial activation are the common ones.

Does this replace CI?

No. CI is still the shared proof. Local contracts just move cheap failures earlier, which is a nice trade if your pipeline is already crowded.

How many contracts should a team start with?

Start with one or two high-value flows. If you launch with eight, the process gets noisy real fast and people stop trustng it.

For me, the nice part of local inbox contracts is that they make email automation feel normal. You are not building a huge platform. You are giving the team a tiny agreement, a small script, and a better place to catch the boring bugs before CI has to.