# SendInkwire

Live fulfillment is enabled. Signed-in public checkout admits eligible one-recipient orders within configured caps. Agent MPP campaigns remain gated by an expiring live-submission approval and final preflight. Payment and physical mail are real.

Agent single-card price: $3.99 USD.
Campaign price: dynamically quoted from recipient count. The response provides the exact customer total and per-letter price.
Payment: Stripe MPP.
Fulfillment: live signed-in checkout with capped automatic admission; agent MPP requires explicit campaign approval and preflight.

Flow:
1. GET /v1/catalog
2. POST /v1/quotes with message, card, handwriting, recipient, and sender
3. Review messageReview, then POST /v1/notes with {"quoteId":"...","approvedContentHash":"..."} and a unique Idempotency-Key
4. Handle the HTTP 402 MPP challenge and retry only after explicit user approval
5. Save the returned readToken; use it as Authorization: Bearer <token> on GET /v1/notes/:id

Constraints: one recipient, US only, 320 characters after handwrite-ascii-v1 normalization. Quote responses show every safe punctuation substitution and reject remaining non-ASCII characters before payment. Review the complete normalized recipient address, final message, and exact public price before approval. Sending physical mail is an irreversible real-world action. Never retry with a different Idempotency-Key after an ambiguous response.

Campaign flow:
1. POST /v1/campaign-quotes with campaign defaults, a messageTemplate, and 1-100 recipients
2. Review every rendered message and the exact campaign price in the response
3. POST /v1/campaigns with {"quoteId":"...","approvedContentHash":"..."} and a unique Idempotency-Key
4. Save the returned campaignToken
5. GET /v1/campaigns/:id/preflight with X-Campaign-Token and stop if ready=false
6. Confirm the paying wallet has the quoted amount on one of the advertised payment networks
7. POST /v1/campaigns/:id/send with X-Campaign-Token, a unique Idempotency-Key, and payment authorization
8. Poll GET /v1/campaigns/:id with Authorization: Bearer <campaignToken>

Campaign safety: externalId must be unique for every recipient. Templates use {{variableName}} placeholders and are fully rendered before payment. A messageOverride can replace the template for one recipient. Review the complete normalized recipient address for every item. The paid campaign is immutable and fulfillment retries replay the stored result instead of mailing duplicates.
Pricing safety: public responses expose only the customer price and per-letter price. Internal cost and margin estimates are not part of the customer approval contract.

Delegated event flow:
1. A signed-in customer creates a scoped, expiring delegation with POST /v1/me/agent-delegations.
2. The agent sends Authorization: Bearer <ink_agent key> plus X-Inkwire-Delegation: <one-time delegation secret>.
3. GET /v1/catalog and use its stationery and handwriting IDs when POSTing /v1/me/events.
4. POST /v1/me/events/:id/recipients, then create missing address requests per recipient.
5. POST /v1/me/events/:id/draft-letters, inspect every message, and POST each recipient approval (with edited message when needed).
6. POST /v1/me/events/:id/publish and inspect the returned frozen campaign draft.
7. POST /v1/me/campaign-drafts/:id/payment with {"confirmed":true,"method":"card"|"mpp","version":N}. Card returns a Stripe Checkout URL; MPP returns a payment handoff and immutable send URL.
8. Before payment, POST /v1/me/campaign-drafts/:id/unlock to cancel an MPP handoff and return the draft to editing. A canceled send URL returns 410 and must never be paid or retried; prepare a new handoff from the returned draft version instead.
9. The customer can inspect activity, inspect delegations, or revoke access with GET /v1/me/activity and GET or DELETE /v1/me/agent-delegations.

Use the version returned by the previous response for every mutation. A 409 means the agent must refetch rather than guessing or retrying stale content. Never prepare payment until every recipient, address, and exact letter has been reviewed.
Delegation safety: an agent key alone has no customer access. A delegation is customer-specific, scope-limited, expires in at most 30 days, and is revocable. Recipient address submission is never delegated and still requires the recipient's one-time token. Activity records contain capability metadata, never addresses or letter copy.