UCP Checker
Guides

UCP Email Matching Explained: Linking an Existing Account When the Issuer Runs the Mailbox, Step by Step

· 16 November 2026 · 10 min read

An agent that signs a shopper in at a store has to answer one question: which of the store's accounts is this person? On 31 October the UCP spec merged PR #998, which lets a store answer it by email address, but only when the identity provider vouching for that address is the one that runs the mailbox. Gmail addresses vouched for by Google, yes; the same address vouched for by any other sign-in service, no.

The rule is on the spec's main branch and planned for the 2026-12-08 release, a plan that can move. It sits inside UCP identity linking's Accelerated IdP Flow, which is already in release 2026-08-25. We built both sides: two test identity providers and a store in UCP Sandbox, and the platform side in UCP Playground. Then we linked the same shopper three ways. Every request, reply and screenshot below comes from those sessions.

What is email matching in UCP identity linking?

Email matching lets a store link a signed-in shopper to an existing account by email, when the identity provider that issued the shopper's grant is the mailbox authority for that email's domain. Everywhere else the store links by the provider's own user id, (iss, sub), and does not merge accounts by email. In the spec's words:

Businesses MAY resolve a grant to an existing account by matching email when all of the following hold: the business has independently established that the grant's issuer is the mailbox authority for the email's domain […]

The conditions, all of which must hold:

  • The store has independently established that the issuer runs mail for the email's domain (for example, a consumer mailbox provider's own domain). The grant cannot claim this for itself.
  • The grant asserts email_verified as the JSON boolean true.
  • The existing account's address was verified by the store itself, not imported from another provider's claim.
  • Nothing is already linked the other way: the account isn't linked to a different sub from the same issuer, and the grant's (iss, sub) isn't linked to a different account.

Once linked, the store MUST resolve that account by (iss, sub) and MUST NOT move the link if the email changes later. It SHOULD tell the account holder that a link was made.

Why the rule is narrow

Before #998, the spec said stores SHOULD NOT auto-link accounts across identity providers by email at all. Any provider can put any address in a token. If a store trusted that, a careless or hostile provider could say "this is [email protected]" and take over Alice's account. A mailbox provider is different: it owns the inbox, so its word on that address is the strongest there is.

The risk that remains is named in the spec: providers that recycle or reassign addresses. Whether a given domain is safe is left to each store to judge.

What changed

Before #998 After #998 (main)
Grant from a provider that runs the mailbox, existing account with that email Don't auto-link; ask the shopper to sign in to the account May link by email, if all four conditions hold
Grant from any other provider, existing account with that email Don't auto-link Don't auto-link (unchanged)
Grant whose (iss, sub) is already linked Resolve by (iss, sub) Resolve by (iss, sub) (unchanged)

It came out of review on #876, a wider proposal that lets a provider prove authority through DNS delegation; #876 is still open. #998 is the simpler first-party case that needs no new DNS records or identity-provider features. Three reviewers approved it, and it merged on 31 October.

How the flow works (Accelerated IdP Flow)

Email matching is one decision inside a flow that already exists in release 2026-08-25:

  1. The store lists the identity providers it trusts in its UCP profile, under config.providers in dev.ucp.common.identity_linking.
  2. The platform signs the shopper in at one of them, once.
  3. For each store, the platform swaps that sign-in for a JWT authorization grant at the provider (token exchange, RFC 8693): short-lived, aimed at that one store (aud), with a unique jti.
  4. The platform presents the grant at the store's token endpoint (grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, RFC 7523).
  5. The store checks it (issuer on its list, signature against the provider's keys, audience, lifetime, jti not seen before), works out the account, and issues its own access token.

Step 5's "works out the account" is where #998 applies.

The setup

Three hosts in UCP Sandbox, built for this guide:

  • Sandbox Mail, a mock mailbox provider. Every account is a mailbox on its own domain, so it is the mailbox authority for that domain. Our test shopper is Alex Rivera.
  • Sandbox ID, a general sign-in service. It signs in any address you type and says it's verified, but it runs no mailboxes.
  • flowers-chain, a flower store that trusts both providers. It already has an account for Alex, with an address the store verified itself and two past orders.

The store's list of mailbox authorities is its own setting ("Sandbox Mail runs mail for this domain"), never read from a token. The platform is UCP Playground's Inspect, which sends each call by hand and keeps every request and reply in the trace on the right.

Step 1: The store offers sign-in through two providers

Inspect's Account card for flowers-chain before linking: the store asks for order:read and order:manage, and offers "Link via" Sandbox Mail and Sandbox ID, plus direct account linking.

The store's UCP profile lists both providers in config.providers, so Inspect offers a "Link via" button for each, beside the store's own sign-in.

Alex signs in at Sandbox Mail once ("Continue as Alex Rivera"). Playground then exchanges that sign-in for a grant aimed at the store. The trace shows the grant decoded:

The trace: token exchange at Sandbox Mail, then the grant decoded: iss Sandbox Mail, sub mbx_7Q2K9ALEX, aud the store, email alex@…, email_verified true.

Step 3: The store matches Alex's existing account by email

The store's token response: HTTP 200, an access token for order:read and order:manage, and the sandbox's decision header naming the rule email_match and the account acct_alex.

All four conditions hold: the issuer is the mailbox authority for the address, email_verified is true, the store verified Alex's address itself, and no other link exists. So the store links the grant to Alex's existing account instead of creating a new one. (The Ucp-Sandbox-Decision header is a sandbox aid so you can see which rule fired; it isn't part of UCP.)

Step 4: The proof: Alex's order history

get_order for NF-ALEX01 returns Alex's Peonies Bouquet order, shipped and delivered.

Reading an order needs a linked account on this store. With the token from Step 3, get_order returns Alex's past order. That's the practical point of the rule: the shopper keeps their history instead of starting a second, empty account.

Step 5: The same email through a provider that doesn't run the mailbox

Now Alex links through Sandbox ID with the same address. The grant looks almost the same, but the issuer is different:

The store refuses: HTTP 400 invalid_grant, "User interaction required: an account with this email already exists here and Sandbox ID is not the mailbox authority for this domain, so the store does not link by email from it. Sign in to that account at the store to link it."

The store refuses with invalid_grant, as the spec says to when user interaction is needed, and nothing is linked. Inspect points to linking directly at the store instead:

Inspect after the refusal: Account not linked; get_order answers identity_required.

Alex changes their email at the store, then links again through Sandbox Mail. The grant still carries the old address, but that no longer matters:

The store's token response: HTTP 200, rule linked: the account was found by (iss, sub), not by email.

The store found the account by (iss, sub) from the first link, as the spec requires. The store's account page keeps the notice it sent Alex and its log of decisions:

The store's account page: two notices to Alex (a sign-in at Sandbox Mail was linked to the account because Sandbox Mail runs that mailbox; the email changed and linked sign-ins stay linked), and the linked sign-in: Sandbox Mail, sub mbx_7Q2K9ALEX, matched by email (mailbox authority).

The store's token endpoint decisions: email_match (Sandbox Mail, token issued), not_mailbox_authority (Sandbox ID, invalid_grant), linked (Sandbox Mail, token issued).

Which identity providers can use it

Only one that runs the mailboxes for the address's domain: a consumer mail provider for its own domain, or a company's own provider for its staff domain. A general sign-in service can't, however good its verification. Across the stores we check, most Shopify stores list Shop (app.shop.accounts) as their identity provider. Shop is a sign-in service, not a mailbox provider, so its grants link by (iss, sub) as before, and #998 doesn't change that.

What it means for stores

  • Keep a list of the mailbox authorities you trust, per domain. The grant can't tell you; the spec makes it your decision, including whether a provider recycles addresses.
  • Only match against addresses you verified yourself. An address imported from another provider's claim doesn't qualify.
  • Tell the account holder when a link is made by email, and resolve by (iss, sub) from then on.

What it means for agent builders

  • Request email and email_verified from the provider. Without them the store can only provision a new account or refuse.
  • Treat invalid_grant as "the shopper must sign in at the store". Fall back to the store's own account linking; don't retry the grant.
  • One provider sign-in can serve many stores. Each store gets its own short-lived grant.

What we'll watch

The 2026-12-08 release, and whether #876's DNS-delegation route follows. Once it ships, we'll look at which stores list identity providers in config.providers, and which of those providers run mailboxes. Every open proposal and recent merge is on our Changes to UCP tracker.

FAQ

What does "mailbox authority" mean in UCP?

The identity provider that runs the mailboxes for an email domain, for example a consumer mail provider for its own domain. Its word that an address is verified is the strongest there is, because it owns the inbox.

Can any identity provider link me to my existing store account by email?

No. Only a provider the store has established is the mailbox authority for your address's domain, and only if your address on the store was verified by the store itself. Otherwise you sign in to the existing account to link it.

Which UCP release has email matching?

It's on the spec's main branch, merged on 31 October 2026, and planned for the 2026-12-08 release, a plan that can move. The flow it sits in, the Accelerated IdP Flow, is in release 2026-08-25.

What happens if my email changes after linking?

Nothing changes for the link. After the first match the store must resolve your account by the provider's user id, (iss, sub), and must not move the link to follow your email.

What does a store return when it won't match by email?

invalid_grant, meaning user interaction is required. The platform should then send the shopper through the store's own account linking.

Is this the same as #876?

No. #876 proposes letting a provider prove authority through DNS delegation and is still open. #998 is the narrower case where the store already knows which provider runs the mailbox.

How can I try it?

Open flowers-chain in UCP Playground's Inspect and use "Link via" on each provider.


About UCP Checker

UCP Checker is the independent validation and observability layer for the Universal Commerce Protocol. We crawl, validate and grade every public UCP manifest we can find, run the merchant directory, the UCP Score, live adoption stats, the vertical guides and the authority-bound vendor map, and track the spec as it evolves so you don't have to — measured from two vantages (what a business declares, and what actually happens when an agent transacts), the same way for everyone, without picking winners.

Sources

Related coverage: UCP identity linking in agentic commerce · UCP agent profiles and verifiable identity · UCP Subscriptions explained, step by step · How UCP's Ask works, step by step

What does a UCP agent find at your store?
Check it once and it gets its own status page.
Check a store

Keep reading

11 Nov 2026 UCP Food Checkout Explained: An Agent Orders Dinner, Step by Step Guides · 14 min 10 Nov 2026 UCP Subscriptions Explained: Purchase Options from Catalog to Order, Step by Step Guides · 12 min 9 Nov 2026 UCP list_price Explained: Reference Prices in Cart, Checkout and Order, Step by Step Guides · 12 min