Set up the account - Origami API

Account holds everything Leads and Send depend on. Most of it you configure once and then forget. Start by confirming what your organization can do:

curl https://origami.chat/api/v3/account \
  -H "Authorization: Bearer $ORIGAMI_API_KEY"

That returns your plan, capability flags, how many agent runs you can have in flight at once, and your project counts. Capability flags matter — features like sender warmup are plan-gated and return 409 WARMUP_UNAVAILABLE if yours doesn’t include them.

Senders

A sender is a mailbox or LinkedIn account Origami sends from. They belong to the organization, so connect once and use across every campaign.

OAuth never completes inside an API call. POST /account/senders/connect returns a handoff URL that a human opens in a browser. Your code’s job is to surface that link, not to follow it.

curl -X POST https://origami.chat/api/v3/account/senders/connect \
  -H "Authorization: Bearer $ORIGAMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel": "email"}'

Any SMTP/IMAP mailbox can be connected straight from the API instead:

curl -X POST https://origami.chat/api/v3/account/senders/imap \
  -H "Authorization: Bearer $ORIGAMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "dana@northwind.io",
    "first_name": "Dana",
    "last_name": "Okafor",
    "smtp_host": "smtp.northwind.io", "smtp_port": 587,
    "smtp_username": "dana@northwind.io", "smtp_password": "…",
    "imap_host": "imap.northwind.io", "imap_port": 993,
    "imap_username": "dana@northwind.io", "imap_password": "…"
  }'

Credentials are write-only — no read ever returns them. Bad credentials fail immediately with SMTP_AUTH_FAILED or IMAP_UNREACHABLE rather than failing silently at send time.

Keeping senders healthy

Task	Call
Set the daily cap, signature, timezone, or gap between sends	`PATCH …/senders/{sender_id}`
Turn on warmup (plan-gated)	`POST …/warmup/enable`
Fix a sender showing `needs_reauth`	`POST …/reconnect`
Send from an alias instead of the mailbox address	`GET …/send-as-aliases`, then set `send_as_email`

A sender whose authorization expired reports needs_reauth and blocks any campaign launch that depends on it. Poll GET /account/senders?status=needs_reauth on a schedule and alert whoever owns the mailbox — a reconnect is another handoff.

Domains and mailboxes

Cold outreach on your primary domain risks your real email. Origami can buy lookalike domains and run mailboxes on them for you.

Find domains

curl -X POST https://origami.chat/api/v3/account/domains/search \
  -H "Authorization: Bearer $ORIGAMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "northwind"}'

Search never charges. It returns availability and price.

Buy them

curl -X POST "https://origami.chat/api/v3/account/domains/purchase?confirm=true" \
  -H "Authorization: Bearer $ORIGAMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains": ["trynorthwind.com"], "forwarding_domain": "northwind.io"}'

Without confirm=true you get a priced preview and nothing is charged. Charges hit the card on file, so this is admin-only and returns 409 NO_PAYMENT_METHOD if there isn’t one. Set forwarding_domain so the apex redirects to your real site — a domain that resolves to nothing hurts deliverability.

Provision mailboxes

curl -X POST https://origami.chat/api/v3/account/mailboxes \
  -H "Authorization: Bearer $ORIGAMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mailboxes": [{
    "domain_id": "'"$DOMAIN_ID"'",
    "local_part": "dana",
    "first_name": "Dana",
    "last_name": "Okafor"
  }]}'

Always async — you get a Job. Once it succeeds the mailbox shows up as a sender.

Domains auto-renew. Turn that off with POST …/renewal/cancel, and change your mind with …/renewal/undo.

Exclusion lists

Two lists — people and companies — checked when leads are sourced and again when people are enrolled. This is your do-not-contact record: customers, competitors, churned accounts, anyone who asked to be left alone.

curl -X POST https://origami.chat/api/v3/account/exclusion-lists/people \
  -H "Authorization: Bearer $ORIGAMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entries": [
    {"email": "dana@northwind.io"},
    {"linkedin_slug": "sam-reyes", "full_name": "Sam Reyes"},
    {"company_domain": "acme.com", "company_name": "Acme"}
  ]}'

Adds are idempotent upserts, up to 1,000 per call. An entry with nothing matchable in it returns UNMATCHABLE_IDENTIFIER — an email, a LinkedIn slug, or a company domain is enough. Each organization has one exclusion list. A project can either share its parent’s or keep a private one:

curl -X PATCH https://origami.chat/api/v3/account/exclusion-lists \
  -H "Authorization: Bearer $ORIGAMI_API_KEY" \
  -H "x-origami-project: $PROJECT_ID" \
  -H "Content-Type: application/json" \
  -d '{"source": "project"}'

Agencies usually want project so one client’s suppression list never leaks into another’s. GET /account/exclusion-lists tells you which is in effect and how many entries it holds.

Credits

curl https://origami.chat/api/v3/account/credits \
  -H "Authorization: Bearer $ORIGAMI_API_KEY"

The balance is reservation-aware: credits committed to running Jobs are already subtracted, so what you see is what you can actually spend. For a monthly breakdown by section, use GET /account/credits/usage?period=2026-08. Reads never cost anything. Sourcing and enrichment do. Per-Job spend is on the Job itself — see credits on the Job object.

Projects

A project is a child organization with its own lists, campaigns, and chats. One per client, if you run an agency.

curl -X POST https://origami.chat/api/v3/account/projects \
  -H "Authorization: Bearer $ORIGAMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Northwind", "monthly_credit_cap": 5000, "enforcement": "hard"}'

hard enforcement blocks spend at the cap; soft tracks it and lets work through. Credits still come from the parent’s wallet either way. Then scope requests with the x-origami-project header — see conventions for exactly which routes honor it.

Webhooks

Rather than polling Jobs, have Origami call you.

curl -X POST https://origami.chat/api/v3/account/webhooks \
  -H "Authorization: Bearer $ORIGAMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Job notifications",
    "url": "https://api.northwind.io/hooks/origami",
    "event_types": ["job.succeeded", "job.failed", "job.needs_input"]
  }'

The signing secret is returned once, at creation. Store it immediately — there is no way to read it back, only to rotate it. Verify every delivery with it before trusting the payload. POST …/test sends a webhook.test event so you can confirm your endpoint works before real traffic depends on it.

Webhooks guide

Event catalog, signature verification, and retry behavior.

API keys

curl -X POST https://origami.chat/api/v3/account/keys \
  -H "Authorization: Bearer $ORIGAMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "CRM sync", "role": "member"}'

Like webhook secrets, the key is shown once. A key can’t be created with a role above its creator’s, and member keys get 403 on admin-only operations — webhook management, key management, and domain purchase. One key per integration. Revoking one takes effect immediately.

Chats

The Origami app’s assistant, over the API. Send a prompt and it does the work, creating lists and campaigns as it goes.

CHAT_ID=$(curl -sS -X POST https://origami.chat/api/v3/account/chats \
  -H "Authorization: Bearer $ORIGAMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Q3 outbound"}' | jq -r '.id')

curl -X POST "https://origami.chat/api/v3/account/chats/$CHAT_ID/messages" \
  -H "Authorization: Bearer $ORIGAMI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Find 50 heads of RevOps at US SaaS companies and draft a campaign"}'

Each message returns a Job, and that Job may come back needs_input if the agent has a question — answer it with POST /jobs/{job_id}/input and the same Job resumes. Use chats when you want Origami to decide the steps. Use the Leads and Send endpoints directly when your code should decide them.

​Senders

​Keeping senders healthy

​Domains and mailboxes

​Exclusion lists

​Credits

​Projects

​Webhooks

Webhooks guide

​API keys

​Chats

Senders

Keeping senders healthy

Domains and mailboxes

Exclusion lists

Credits

Projects

Webhooks

API keys

Chats