API vs desk: who should send the envelope

Ops teams do not need a philosophy of APIs. They need a rule for who starts the envelope. The Inkpacket desk is the human path: upload or use a template, place fields, send, then void, correct, or resend on the same id. The public API is the system path: mint an org-scoped Bearer token, create from a template, fill known values, send with an Idempotency-Key, and listen for a signed webhook.

Both paths share one monthly envelope cap. Free allows 5 packets a month. Hitting the cap returns HTTP 402 and code ENVELOPE_LIMIT. Each API token allows 120 requests per minute per token. Over that limit, /api/v1 returns HTTP 429 with a Retry-After header. Inkpacket does not send X-RateLimit headers. /api/v1 does not return HTTP 429 for traffic. Access-code 429 is a PIN lockout, not a send throttle. The developer walkthrough is public API and signed webhooks. Desk help is Docs.

Use the desk when a person is deciding

If a teammate is looking at a PDF and choosing a signer, they should stay on the desk. That includes first-time layouts, one-off uploads, envelope admin after a typo, and any send where the operator needs to see the page before they hit send.

• New or changing PDFs — place signature, date, text, initials, checkbox, and select marks yourself.
• Void, correct, or resend on an in-flight envelope. Those verbs keep the same envelope id — envelope admin.
• Copy a signing link when Resend is not configured. The desk says Invite email was not sent and still shows the URL.
• Publish a Web Form or start a bulk job. Those screens are operators, not cron.

Members can send. Owners and admins invite and mint tokens. Templates, envelopes, and audit events stay inside the workspace. The home page is the same loop in fewer words: prepare, send, file.

Use the API when your system already has the list

If an HRIS, CRM-adjacent store, or intake app already knows the recipient, do not retype them on the desk. Save the PDF as a workspace template once. Then POST /api/v1/packets with templateId, fill known text, and POST /api/v1/packets/:id/send with an Idempotency-Key if the worker may retry.

1. Mint a token in Settings as Authorization: Bearer ip_…. Store it as a secret, not in a browser bundle.
2. Create from the template. Tokens never cross workspaces.
3. Send. The response includes signingUrl, embedUrl, emailSent, and emailError.
4. Hand the URL to mail you already send, or iframe embedUrl on a portal you already operate — embedded signing.
5. Verify webhooks. Update your own record. Do not poll the list unless you are debugging.

Send still accepts reminder interval, expiration, an optional access code, recipients, and routingMode. Those options are the same decisions a person makes on the send form — how to choose an envelope expiry and access codes for sensitive envelopes. The API does not invent a layout. If the template is wrong, fix it on the desk first.

Retries are idempotent on create and send

A flaky worker that POSTs send twice without a key can surprise you. Send the Idempotency-Key header on create and send. That is a client retry, not a webhook retry. Webhook deliveries are a different queue — webhook retries explained. Envelope-admin routes sit next to send: void, resend, and correct on the same id.

Do not use the API to place fields. Suggest starting layout is a page-count heuristic on the desk, not a model, and there is no field-detection route in this pass. Do not use the API as a hidden Web Form. If strangers should start the envelope, publish /form/SLUG — bulk send vs Web Forms.

Caps both paths share

Send, bulk send, Web Form fills, and POST /api/v1/packets/:id/send share the monthly envelope cap. Free at 5 packets a month is the Free gate. Starter is 20 envelopes — more than Free — plus 3 published Web Forms. Seat counts are planning numbers; invite does not refuse when a workspace is full. Billing is published, not charging. Checkout is not open. Workspaces stay on Free unless you later turn charging on.

Mail, SMS, Drive, and card collection do not pretend to succeed without keys. Resend missing: copy the link. Text-message (SMS) is coming soon. Drive missing: Drive not configured. Stripe off: Payments not live. The envelope still exists. GET /api/v1/health reports the same flags Settings shows.

A split you can write on a wiki

• Person has the PDF in front of them → desk.
• System has the recipient and a saved template → API.
• Stranger should start the envelope → Web Form, not a hidden API form.
• Known list, human operator → bulk send.
• Status must update another database → webhook, verified, not an iframe event.

Ops teams get into trouble when they clone a second envelope because the first email was lost, or when they put a token in a frontend. Resend the existing link. Keep the Bearer secret on a server. Read how to read an audit trail when someone asks what happened. Then open a workspace on Free and send one envelope each way so the split is muscle memory, not a slide.