How do you extract a single-use activation link from a captured sign-up email so the extraction survives wording changes?

## A captured message is structured data When a run reads a message the product sent, it does not see what a person sees. It sees a record with parts: envelope fields (who it went to, who it came from, when it was accepted), a subject line, headers — including any header the sending code chose to stamp — a plain-text body part, a markup body part, and attachments. The single-use value the case needs sits somewhere inside that record, and the whole skill of this step is choosing a handle the record guarantees rather than one today's copy happens to supply. Two shapes come up. The first is a **link** whose address carries the single-use value, either as a path segment or as a named parameter. The second is a **short code** printed in the body for a person to type. The link is much easier, because an address has structure to key on; the bare code needs more care and is covered below. ## Why matching on the copy is the wrong handle The tempting first version matches the sentence: find "Click here to confirm your account" and take the link beside it. That works on the day it is written and then decays, because the sentence and the link are owned by different people on different schedules. | Handle | Who changes it | How often it changes | | --- | --- | --- | | The sentence around the link | Copywriters, translators | Every campaign and every locale | | The button or link label | Designers, translators | Often | | Paragraph order in the body | Template redesign | Occasionally, without notice | | The route path the link points at | Product engineers | Rarely, and with a migration | | The parameter name carrying the value | Product engineers | Rarely | | A header the sending code stamps | Product engineers | Rarely; it exists for machines | Everything in the top half of that table is prose. Everything in the bottom half is emitted by code, reviewed in a change, and visible to whoever breaks it. A case keyed on the top half gets broken by people who do not know a test exists. A case keyed on the bottom half breaks only when the thing under test actually moved. ## The selection rule, step by step 1. **Choose the body part deliberately** — plain-text or markup — and say which in the helper. They are not the same document and they do not always carry the same links. 2. **Collect every link target in that part.** Do not stop at the first one. 3. **Filter by something code emits**: the path segment the activation route owns, or the presence of a named parameter. 4. **Assert that exactly one candidate survived.** Zero matches and several matches are different failures, and neither should be silently resolved by taking the first. 5. **Read the value out by parameter name**, never by slicing the address at a fixed offset — one extra parameter or a host change moves every offset. Step four is the one that gets skipped and the one that pays. A body typically holds a footer link, an unsubscribe link, a help link, sometimes a preferences link. A template change that adds one more is not supposed to break the suite, but a take-the-first-link extraction will quietly start asserting against whichever one now comes first, and the failure it eventually produces points anywhere but here. ## When the value is a bare code A six-character code has no structure to filter on, so give it some. In rough order of durability: - **A marked element.** Ask that the template wrap the code in an element carrying a stable identifying attribute. Cheapest and most durable, and it costs the sending team almost nothing. - **A stamped header.** The sending code puts the same value in a header beside the body. Machines read it, people never see it, translators cannot touch it. - **A guaranteed delimiter**, such as the code sitting alone on its own line, combined with a shape constraint. - **A shape constraint alone** — six upper-case characters, say — is the weakest option, because an order reference or a promotional code in the same body matches it too. If you must use it, assert that exactly one match exists so a second matching string fails loudly rather than silently winning. ## Failing in a way the next reader can use When extraction fails, whoever reads the run has no mailbox to open. The failure message has to carry the evidence: the recipient the case registered, the subject line that arrived, how many candidates passed the filter, and what they were. That turns "activation link not found", which forces a re-run to learn anything, into "three links present, none under the activation route", which is already a diagnosis. ## Make it a contract, not a workaround The durable version of this is not a cleverer extraction. It is asking the team that owns the sending code for one stable handle — a documented parameter name, a marked element, or a stamped header — and writing it down. Once that exists, every suite extracts the same way, template redesigns stop breaking tests, and the extraction helper shrinks to a few lines nobody has to think about again.