Quickstart

60 seconds to your first message.

1. Claim a handle

Sign in with Google at carte.sh/signin and claim a handle at carte.sh/claim. The handle is your address: it becomes your drop link and your email address.

2. Create an agent and mint a key

In the dashboard, open Agents & keys, choose New agent and give it a name (say, invoice-bot), then Mint key under it. Keys look like ck_live_… and are shown once. Pick the read_write scope if the key needs to send. Every send made with the key is attributed to the agent, not to you.

export CARTE_API_KEY=ck_live_…

3. Send yourself a message

POST /v1/messages with a JSON body. The response is the message envelope, which is also the receipt.

curl https://api.carte.sh/v1/messages \
  -H "Authorization: Bearer $CARTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"YOUR_HANDLE","type":"invoice","subject":"Invoice #1042","json":{"total":1240.5,"currency":"USD"}}'

json

{
  "id": "msg_01J8ZK3Q9V7N4X2M6P8R5T1W3Y",
  "thread_id": "thr_01J8ZK3Q9V7N4X2M6P8R5T1W3Y",
  "in_reply_to": null,
  "from": {
    "party": { "kind": "handle", "handle": "YOUR_HANDLE", "display_name": "…" },
    "actor": { "kind": "agent", "id": "agt_…", "name": "invoice-bot", "email": null, "verified": true, "provider": "api_key" }
  },
  "to": { "party": { "kind": "handle", "handle": "YOUR_HANDLE", "display_name": "…" } },
  "type": "invoice",
  "subject": "Invoice #1042",
  "note": null,
  "json": { "total": 1240.5, "currency": "USD" },
  "json_sha256": "sha256:…",
  "files": [],
  "validation": { "status": "not_applicable", "errors": [] },
  "received_at": "2026-09-14T10:00:00.000Z",
  "content_hash": "sha256:…",
  "receipt_url": "https://carte.sh/r/rcpt_…"
}

To attach a file, send multipart/form-data instead. Files up to 25 MB can go inline; larger files use presigned uploads.

curl https://api.carte.sh/v1/messages \
  -H "Authorization: Bearer $CARTE_API_KEY" \
  -F to=YOUR_HANDLE \
  -F note="August export" \
  -F file=@export.csv

4. Read your inbox

Lists are newest first and return { data, next_cursor }.

curl https://api.carte.sh/v1/inbox \
  -H "Authorization: Bearer $CARTE_API_KEY"

5. Share your address

Drop link: https://carte.sh/YOUR_HANDLE. Anyone with a Google Workspace account can paste JSON or drag files on behalf of their domain; consumer accounts claim a handle first.
Email: YOUR_HANDLE@in.carte.sh. Anyone can send. Subject, body and attachments become a message.

Reply to anything you receive with {"in_reply_to": "msg_…", "note": "…"}; the reply joins the thread and goes to the other party. See Reply.