Idempotency-Key on API sends

A worker that POSTs /api/v1/packets/:id/send will retry when the socket dies. Without a key, that retry is a second send — a second envelope, a second invite, a second audit trail. An Idempotency-Key is how you tell Inkpacket the second POST is the same attempt. The same key with the same body returns the original response. The same key with a different body returns 409.

Create-from-template start to send is create an envelope from a template via the API. Who should click versus who should POST is API vs desk for ops teams. Desk help is Docs. This guide is the header: where it applies, what it stores, and what it will not save you from.

Where it applies

Send the header on create, fill, fields, and send if the client may retry. The key is at most 128 characters. Inkpacket hashes the method, path, and JSON body. A stored row is scoped to the organization — another workspace cannot replay your key. Successful and client-error responses can be stored. A 5xx is not committed, so a later retry with the same key is still a fresh attempt after a server miss.

Void, resend, and correct do not use that header. Those verbs are already in-place on one envelope id. Resend does not mint a twin because you clicked twice. If you need another copy of the link, resend. If you need a different address, correct. If the deal is off, void. Do not invent a second create-and-send to “retry” admin.

Replay versus conflict

• Same key, same body — replay the stored status and JSON.
• Same key, different body — HTTP 409, Idempotency-Key was reused with a different request.
• No key — every POST is fresh. Timeouts can double-send.
• Key longer than 128 characters — HTTP 400.

Mint an org-scoped Bearer token in Settings first. Members can send from the desk; they cannot mint tokens. Authorization: Bearer ip_… on /api/v1/packets and the envelope sub-routes. GET /api/v1/health is public. 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. Access-code 429 is a PIN lockout, not this header.

What it does not do

An Idempotency-Key is not a webhook retry. Outbound POSTs to your URL are a different queue — first try immediately, hourly job, 5 attempts, then failed. There is no test-send or replay button for those deliveries. When webhook delivery fails is that honesty. Do not reuse a send key as a stand-in for a missed envelope.completed.

It is not a monthly cap waiver. Send still checks remaining envelopes. Free allows 5 packets a month. Hitting the cap returns HTTP 402 ENVELOPE_LIMIT. A replay of a successful send does not spend a second envelope. A fresh send without a key does. Read the 402 body before you POST again with a new key.

A draft is not a send

Create-from-template can sit as a draft. The cap fires on send. Fill and fields change the draft; they do not invite anyone. If create committed under a key and you later change the body, do not reuse that key. Store a key per logical attempt — one for create, one for send — or you will 409 the moment the payload differs.

Practical habits

1. Generate a key per user-visible action in your worker, not per HTTP library retry loop you cannot see.
2. Keep the body byte-stable. Reordered JSON that hash-differs is a 409.
3. Log the replay. A 200 on the second POST is not proof a second signer was invited.
4. Rotate tokens in Settings if a key leaks. Staging should not share production’s Bearer secret.

Reminders go out by email today. Text-message (SMS) is coming soon. Email still soft-fails after a successful send. The response includes signingUrl, embedUrl, emailSent, and emailError. Copy the URL if Resend is missing. Text-message (SMS) is coming soon. Do not POST send again because a text is not part of this send — that is a second envelope.

Caps and what is not open yet

Free allows 5 packets a month. Free at 5 packets a month is the live cap desk send, bulk rows, Web Form fills, and API send share. 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.

Text-message (SMS) is coming soon. Drive missing: Drive not configured. Stripe off: Payments not live. None of those flags mint or ignore an Idempotency-Key. The FAQ and API on Features point at the same routes.

Put the header on create and send. Replay the original response when the socket flakes. Stay on that envelope id. Then listen for status on a webhook if your system needs completed — listen for envelope status webhooks. Open a workspace on Free — see published pricing — mint a token, and retry one send on purpose so you have seen a replay, not just a timeout.