Idempotency-Key on create, fill, and send

A worker that creates an envelope from a template, fills recipient slots, then POSTs send will retry when the socket dies. Send an Idempotency-Key on create, fill, fields, and send if the client may retry. The header is at most 128 characters. Inkpacket hashes the method, path, and JSON body. The same key with the same body replays the stored response. The same key with a different body returns 409. That is create-fill-send-key honesty: one key per logical step, not one key taped across create-then-fill-then-send, and void, resend, and correct still do not use that header.

The send-focused header story is Idempotency-Key on API sends. The fill step itself is API fill then send. Create-from-template is create an envelope from a template via the API. Desk help is Docs. This guide is why the three POSTs cannot share a key.

Ask Inkpacket for Idempotency-Key on create, fill, and send to open this article. Ask how the API works to open help. Ask how to create an api token to open Settings #tokens. Those phrases stay on the product screens. This article is the public version of why a 409 on send usually means you reused the create key.

One key per step

• POST /api/v1/packets (create from template) — key A. A draft exists. The monthly cap has not fired yet.
• POST /api/v1/packets/:id/fill or /fields — key B. Recipients and marks change. Nobody is invited.
• POST /api/v1/packets/:id/send — key C. This is the send. This is the envelope that counts.
• Same key, same body — replay. Same key, different path or JSON — HTTP 409, Idempotency-Key was reused with a different request.

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. Key longer than 128 characters returns HTTP 400. No key means every POST is fresh — timeouts can double-create or double-send.

What the header skips

• Void, resend, and correct. Those verbs are already in-place on one envelope id.
• Webhook delivery. Outbound POSTs are a different queue — when webhook delivery fails.
• The monthly cap. A replay of a successful send does not spend a second envelope. A fresh send without a key does.
• PIN lockout. Access-code 429 is a signer door, not this header — access-code 429 versus API rate limit.

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. Send volume over the monthly cap is HTTP 402 ENVELOPE_LIMIT, not 429. The send guard is HTTP 402 ENVELOPE_LIMIT.

The click-path

1. Generate a key per user-visible action in your worker — create, fill, send — not per HTTP library retry you cannot see.
2. Keep each body byte-stable. Reordered JSON that hash-differs is a 409.
3. If send 409s, check whether you reused key A. Mint key C. Do not POST create again “to be safe.”
4. Read emailSent and signingUrl on send. If mail skips, copy the URL. Do not send again with a new key.
5. If send returns ENVELOPE_LIMIT, stop. Checkout will not waive the month.

Fill is not send. A draft that exists under key A is not an invite. If create committed and you later change the template payload, do not reuse key A. API fill then send is that order. 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. Drive archive still waits for completed. Stripe off: Payments not live.

Ask and the desk

Ask Inkpacket for Idempotency-Key on create, fill, and send to open this article. Ask how to use the API to open help. Marketing Ask stays site Q&A and deep links. It will not mint a Bearer token or POST send from this article. On a phone, Settings is a drawer row — tokens are still an owner or admin card, not a member control.

Caps and what is not open yet

Create and fill are not sends. Send is. 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. Hitting it returns HTTP 402 ENVELOPE_LIMIT. 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. Those flags do not mint or ignore an Idempotency-Key. The FAQ and Public API use Send an Idempotency-Key on create, fill, fields, and send in the same words.

Key A for create. Key B for fill. Key C for send. Replay the original response when the socket flakes. Stay on that envelope id. Open a workspace on Free — see published pricing — mint a token, and retry create then send on purpose so create-fill-send-key honesty is a 409 you have already read, not a second envelope you filed by accident.