For agents, and the people who build them.

Ask the operator for the configured receiving address and allowlist admission. Use subject Popular Demand draft and a plain-text body containing only PurchaseInput JSON. Keep prices uncertain with exploration. This draft path does not confirm a pricing policy. Popular Demand replies with a private draft review link. The human must verify an account and activate. A draft reply alone grants no maintenance authority. Attachments and HTML are ignored.

{
  "raw_request": "I might buy a compact espresso machine before summer. Find something meaningfully better.",
  "country": "US",
  "currency": "USD",
  "destination": {
    "postal_code": "94103",
    "scope": "national_parcel"
  },
  "pricing_policy": {
    "mode": "explore"
  },
  "source": "personal_agent"
}

This adapter is disabled by default. It requires a verified owner to approve one exact admitted mailbox, selected Requests, explicit permissions and expiry. The owner can approve creation before a first Request exists. New Requests join that grant’s scope, up to 100 Request IDs. Other account Requests stay outside its scope. Read the private challenge and bind before using subject Popular Demand command with one plain-text EmailCommand JSON body. A sender address or thread never grants authority. Create/read/update/close/reaffirm are scoped separately. Creation requires actual user agreement and user_confirmed: true. An uncertain price can remain explore. No operation accepts a deal, places an order or pays. Candidate-Offer and seller-context notices require separate consent. Use the EmailCommand schema in OpenAPI.

For receipt_too_large on read_offer (or the deprecated read_plan), send a fresh command_id and an optional section. Use section kind overview for identity, totals, blockers and original conditions; lines for a page of exact quoted lines; need with need_id for original alternatives; or policy with name warranty, returns or cancellation for one full policy. Lines and need sections accept offset starting at zero and limit from one to five; follow next_offset until null. Match the section plan_id (the Offer ID), plan_version and original_snapshot_digest before combining original sections. Optional expected_offer_version (expected_plan_version on read_plan) rejects a changed Offer. Each part is incomplete and each current read has its own as_of time. An original digest is not a signature or approval. Read a fresh overview last; check current_context and current blockers, not only the original price. When present, context_diagnostics explains a changed Request version, unavailable or revised seller Quote, or an Offer that is no longer prepared. It exposes observed versions/states, not new draft seller terms. Empty codes establish only current binding; inspect current evaluation for costs, price qualification and expiry. Do not rebind an old delivery quote to new conditions. Never infer acceptance or payment authority from these parts. A read_offer (or read_plan) reply in full or its overview section records that this mailbox read that Offer version, so Popular Demand may skip its one reminder email to the user: promptly tell the user the price and deadline of that Offer. A list_offers page records no read. A rate_limited creation receipt is a stable rejection. Retrying that exact command cannot create a Request later. Wait until the next UTC hour and use a new command_id only if the user still wants to save this intent. For create, ordinary read, update, close or reaffirm, optional request_format overview returns request_overview instead of the full Request. It explicitly omits Need details and root product fields; it is not complete purchase conditions. Full remains the default and no term is clipped. For read only, section kind need with need_id returns current Need description, quantity, hard terms and a page of alternatives. Use offset and limit as above. Do not combine section and request_format. Optional expected_request_version pins a read to the current version. Match request_id, request_version and conditions_digest with the overview before combining conditions; each current read has its own as_of. These are current Request conditions, not an Offer original snapshot. Use changes need_quantity_changes with existing need_id and quantity for a small authorized quantity edit. Never combine it with purchase_spec. Null means unknown; the edit does not multiply budgets or confirm other conditions. Use the current Request version. Use changes need_term_changes with existing need_id and selected terms warranty_months_min, returns_days_min or authorized_seller_required for a small user-authorized hard-term edit. Omitted terms stay unchanged; explicit null removes only that condition. It preserves alternatives, quantities and ceilings. A changed quantity or hard-term set resets conditions_confirmed unless the change explicitly supplies conditions_confirmed=true under current user instructions. Never infer a larger quantity from a good deal; soft confirmation is not payment authority. It may combine with quantity changes, never with purchase_spec. Read the current Need section before an ambiguous edit. Use changes need_option_changes to replace one existing Need's complete acceptable-option set, optionally its description. Do not append old options or select one automatically. An empty option set is unresolved. Replacement defaults conditions_confirmed to false; true requires current user authority for these exact options. This preserves other Needs, quantities, hard terms and ceilings. Targeted edits may combine, never with purchase_spec. Changing raw_request still unconfirms Needs. For create and update, send the delivery postal code as destination.postal_code when the user shares it (US ZIP 12345 or 12345-6789, or a 7-digit Israeli code). It is optional to save but required before an Offer can be prepared; postal_code_invalid means it does not fit the Request country. A create receipt may list possible_duplicate_of: open Requests of the same user that look like the new one. The new Request is saved anyway; if it is the same purchase, update or close the extra one. For update, changes may_commit true records the user's own statement that their agent may place a payment hold if an Offer fits; false withdraws it. It is recorded provenance, never a permission from Popular Demand, and email never places a hold. All replacements still face each transport body limit. The owner browser and REST/MCP API do not bypass the 32 KiB HTTP input cap. Bounded reads do not permit an oversized replacement. A reply cannot authorize payment.