---
title: "Send a card"
method: POST
path: "/v1/cards"
tags: ["cards"]
---

# Send a card

`POST /v1/cards`

## Request

- Base URL: `https://api.noerrands.com/c/cards`
- URL: `https://api.noerrands.com/c/cards/v1/cards`
- Auth: HTTP bearer

Mail the card a quote describes: CONSEQUENTIAL and charged (899 credits handwritten, 399 printed) -- a real card goes to a real person. Takes the quote_id with confirm: true. Sensitive write: it requires the human's approval of the preview (design, full message, recipient and address, tier, price, dispatch date). The same quote_id never sends or charges twice; a card scheduled for a later day can be cancelled for a full refund until it leaves.

## Request body

- object
  - `quote_id` string, required: From preview_card. Repeating it never charges twice.
  - `confirm` true, required: Must be true: the human has seen the preview and approved sending and paying for it.

## Response `200`

Success.

- object
  - `card_id` string, required: Opaque id, "cd_...". Use it with get_card and cancel_card.
  - `status` 'scheduled' | 'submitted' | 'in_production' | 'mailed' | 'delivered' | 'returned' | 'cancelled' | 'failed', required: scheduled (held until dispatch_on) -> submitted -> in_production -> mailed -> delivered; or returned, cancelled, failed.
  - `tier` 'handwritten' | 'printed', required: handwritten: a folded card written with a real pen, in a stamped envelope. printed: a 6x9 postcard-style card, message printed on the back where anyone handling it can read it.
  - `dispatch_on` string, date, required: The day the card goes to the provider.
  - `estimated_arrival` object, required
    - `earliest` string, date, required: Earliest likely delivery date.
    - `latest` string, date, required: Latest likely delivery date. USPS does not guarantee it.
  - `credits_charged_cents` integer, required
  - `balance_cents` integer, required: General credit left.

## Other responses

- `400`: invalid_request
- `401`: unauthorized. Carries WWW-Authenticate: Bearer resource_metadata="..."
- `402`: insufficient_credits, with required_cents and topup_url.
- `403`: forbidden_scope: a write tool called with a read-only key.
- `404`: not_found
- `409`: idempotency_conflict: the same quote is being sent right now.
- `429`: rate_limited
- `502`: provider_error

---

[API](https://skmtc.dev/noerrands/apis/no-errands-cards-api.md) · [All operations](https://skmtc.dev/noerrands/apis/no-errands-cards-api/llms.txt) · [OpenAPI document](https://skmtc.dev/noerrands/apis/no-errands-cards-api/revisions/f39a5d132f73?raw)