Tags and the per-run purge

A tag is a label on an inbox. Most suites tag every inbox a CI run creates with the run, such as run-4711, and add whatever else they group by, such as the branch or the suite. When the run ends, one call deletes every inbox of the tag with its mail.

Tagging

Tags are given when the inbox is created:

{ "name": "signup", "tags": ["run-4711", "checkout-suite"] }

• An inbox carries up to ten tags.
• A tag is 1 to 64 letters, digits, dots, hyphens or underscores, starting and ending with a letter or digit. Tags are stored in lower case, so Run-4711 and run-4711 are the same tag.
• A tag needs no setting up: it exists exactly as long as some inbox carries it.
• Tags are not part of the address. Parallel runs that want readable addresses put the run in the inbox’s name, or share one inbox and use different local parts.

Listing by tag

• GET /v1/inboxes?tag=run-4711 lists the inboxes carrying the tag; tag= with no value lists the untagged ones.
• GET /v1/messages?tag=run-4711 lists the mail of those inboxes, newest first.
• GET /v1/inboxes/tags lists the tags in use with how many inboxes carry each, the tag with the newest inbox first; q keeps the tags that start with it.

The per-run purge

curl -sS -X DELETE "https://api.waridex.com/v1/inboxes?tag=run-4711" \
  -H "Authorization: Bearer $WARIDEX_API_KEY"

{ "tag": "run-4711", "deletedInboxes": 12, "deletedMessages": 40 }

DELETE /v1/inboxes?tag= needs the inbox:delete scope. It deletes every inbox carrying the tag, whatever other tags it carries, together with its messages and their stored copies; the inboxes stop receiving mail at once.

• A tag no inbox carries answers 200 with zeros, so a teardown step that runs twice does no harm.
• Without a tag the call is refused with 400 tag.required: it never deletes everything.
• In the rare case that an inbox cannot be removed yet, the call answers 503 store.unavailable with the counts so far. The inboxes already refuse mail; repeat the call, or the hourly clean-up finishes the job.

Run the purge in your suite’s teardown so it happens whether the tests passed or not. An inbox that escapes it stays until it expires, if it was given an expiry, or until you delete it; its mail goes when the plan’s retention runs out.