FOR AGENTS & DEVELOPERS

Send to a person.
Not an address.

OnceAsk resolves a known recipient to a permissioned, one-time delivery token. With supported OnceAsk fulfillment actions, your agent can trigger a physical delivery without putting the recipient's street address into model context.

resolve_delivery({ query: "Jane Smith" })→{ status: "authorized", deliveryToken: "oa_del_…" }

60-SECOND QUICKSTART

One scope. Two agent actions.

The resolve_delivery scope can resolve a delivery and request the recipient's permission. It does not grant full contact-record access.

Create a private-delivery key

Use a least-privilege key. Do not give a delivery agent read_contacts unless it genuinely needs full contact records.

Create account Already have an account?

Make the first call

Resolve by a name the user already knows, or use a OnceAsk contact ID when you have one.

curl -s https://onceask.com/_api/v1/delivery/resolve \
  -H "Authorization: Bearer $ONCEASK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"Jane Smith","purpose":"send a birthday gift"}'

If permission is already present:

{
  "status": "authorized",
  "deliveryToken": "oa_del_…",
  "allowedAction": "physical_delivery"
}

Handle permission_required

Do not improvise or ask for the address in chat. Call the explicit next action with the returned recipient ID.

{
  "status": "permission_required",
  "recipientId": "…",
  "nextAction": "request_delivery_permission"
}

curl -s https://onceask.com/_api/v1/delivery/request-permission \
  -H "Authorization: Bearer $ONCEASK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contactId":"RECIPIENT_ID"}'

OnceAsk emails the secure permission link when an email is on file. Otherwise it returns the link so your agent or user can send it through another trusted channel. Neither response reveals the email or street address.

Then retry resolve_delivery.Once authorized, use send_handwritten_card to send through Handwrytten without exposing the destination to the agent. See MCP, OpenAI, Claude, Cursor, and fulfillment examples →

Address stays private

Raw address retrieval is not the default primitive. Delivery tokens are short-lived and one-time.

Permission is explicit

A contact existing in a vault does not imply authorization. OnceAsk checks an active recipient grant before issuing a token.

Freshness is built in

Recipients own their live address. Missing or stale delivery identity routes through confirmation instead of returning bad data.

ONE RESOLUTION CONTRACT

Every agent gets a safe next action.

Use the MCP tool or REST endpoint. The response is intentionally structured so an LLM can act without guessing about consent.

authorized

Use the short-lived token with a supported OnceAsk fulfillment action. That action does not return the street address.

permission_required

Call request_delivery_permission. OnceAsk routes the recipient through explicit consent.

address_update_required

Call request_delivery_permission. The same secure flow collects or confirms the current address.

ambiguous

Ask the user which matching person they mean, then retry with recipientId.

not_found

Collect or create the recipient first.

MCP + REST

Resolution, permission, and fulfillment all work in MCP.

Connect to https://onceask.com/_api/mcp with the same delivery-scoped key. The model can resolve a person, request consent, list handwritten cards, and fulfill the authorized delivery without raw-address access.

Start the quickstart

Send to a person.Not an address.