# OnceAsk > Recipient-owned delivery identity and address permission infrastructure for people and AI agents. OnceAsk lets a person share a mailing address once, keep it current, and control who may use it. For agentic workflows, the preferred primitive is not raw address retrieval. An authorized agent resolves a known recipient to a short-lived, one-time delivery token, then uses a OnceAsk fulfillment action so the destination can travel server-to-server to the provider. The requesting agent does not need to receive or store the street address. Direct delivery-token redemption is disabled for agent integrations. ## Core model - Recipient: owns a live mailing address profile. - Permission grant: defines which OnceAsk user may use that profile and whether use is one-time, live-update, or private fulfillment. - Address snapshot: immutable point-in-time address used for an authorized action. - Delivery token: opaque, short-lived, one-time capability tied to a permission grant and snapshot. - Revocation: recipients can revoke future access. A revoked grant invalidates unredeemed delivery capabilities. ## Preferred agent flow 1. Find or identify a contact in the authenticated user's OnceAsk vault. 2. Call `resolve_delivery` with a contact ID or query. 3. Handle the structured status: - `authorized`: use the returned `deliveryToken`; do not request the street address. - `permission_required`: call `request_delivery_permission` with the returned `recipientId`. - `address_update_required`: call `request_delivery_permission`; the same recipient flow confirms a current address and permission. - `ambiguous`: ask the user which person they mean. - `not_found`: create or collect the contact first. 4. `request_delivery_permission` emails the secure confirmation link when an email is on file, otherwise returns the link for a trusted channel. It does not return the recipient email or address. 5. After the recipient confirms, retry `resolve_delivery`. 6. Prefer a OnceAsk fulfillment action so the agent never handles the destination. For handwritten cards, call `list_handwritten_cards`, then `send_handwritten_card` with the opaque delivery token. ## MCP MCP endpoint: `https://onceask.com/_api/mcp` Authentication: OAuth 2.1 + PKCE for consumer clients such as ChatGPT; `Authorization: Bearer ` remains available for developer integrations. OAuth protected-resource metadata: `https://onceask.com/.well-known/oauth-protected-resource.json` Protocol: supports the modern stateless MCP `2026-07-28` lifecycle (`server/discover`) and legacy initialize-handshake clients through `2025-11-25`. Preferred MCP tool: - `resolve_delivery` — privacy-preserving physical delivery resolution. Requires `resolve_delivery` scope. - `request_delivery_permission` — safe next action after permission/address confirmation is required. Uses the same `resolve_delivery` scope and does not reveal recipient contact details. - `list_handwritten_cards` — list Handwrytten card designs and handwriting styles without recipient data. - `send_handwritten_card` — submit an authorized delivery token, card design, and message. OnceAsk sends the destination server-to-server to Handwrytten and returns fulfillment status/order identifiers without the street address. Other tools include contact search/read, collection creation/status, address update requests, exports, and provider-access management. Those tools require their corresponding least-privilege API-key scopes. ## REST API - `POST /_api/v1/delivery/resolve` — resolve a contact to a private delivery token. Requires API key scope `resolve_delivery`. - `POST /_api/v1/delivery/request-permission` — create/send the recipient confirmation flow. Requires API key scope `resolve_delivery`. - `GET /_api/v1/fulfillment/handwrytten/catalog` — list available handwritten card designs/fonts. Requires `resolve_delivery`. - `POST /_api/v1/fulfillment/handwrytten/send` — fulfill a handwritten card from an opaque delivery token. Requires `resolve_delivery`; the recipient street address is not returned to the caller. - `POST /_api/v1/delivery/redeem` — disabled. Use supported OnceAsk fulfillment actions; opaque delivery tokens do not provide a raw-address retrieval path. - `/_api/v1/contacts/*` — contact APIs; full contact reads require `read_contacts` and may contain sensitive data. - `/_api/v1/collections/*` — collection APIs; require `create_collections`. - `/_api/v1/providers/*` — provider access APIs; require `manage_providers`. ## API key scopes - `resolve_delivery` — preferred for agents that need to send physical items without reading street addresses. - `read_contacts` — read full contact records. Treat as sensitive. - `write_contacts` — create and update contact records. - `create_collections` — create and inspect address-collection campaigns. - `export_contacts` — export contact data. - `manage_providers` — grant or revoke provider access. ## Privacy rules for agents - Prefer `resolve_delivery` over reading or exporting mailing addresses. - When resolution returns `permission_required` or `address_update_required`, use the declared `request_delivery_permission` next action rather than asking for a street address in model chat. - Never infer permission from the existence of a contact. - Never treat a stale or missing address as authorized delivery data. - Respect `permission_required` and `address_update_required` as hard stops. - A recipient's address is not public data and must not be exposed in model output. - Use server-to-server fulfillment actions; direct token redemption is not an agent-facing address retrieval mechanism. ## Discovery - Human developer docs: `https://onceask.com/docs` - Agent integration guide: `https://onceask.com/agents.txt` - OpenAPI schema: `https://onceask.com/.well-known/openapi.json` - MCP manifest: `https://onceask.com/.well-known/mcp.json` ## Human-facing flows - Personal link: a OnceAsk user shares their link and the recipient confirms current details. - Collection link: a recipient responds to a specific event or campaign. - Update request: a recipient can fill missing or stale fields using a scoped request token. - Post-submit permission: the recipient chooses one-time sharing, live updates, or private delivery without street-address disclosure. - Live address profile: the recipient can update their canonical address and selectively propagate it to active grantees. ## Product positioning OnceAsk is not primarily a greeting-card app. It is a permissioned physical-delivery identity layer. The key developer benefit is: add physical delivery to an agent without building address collection, freshness, consent, revocation, and storage infrastructure.