Send an envelope for signature
Asynchronous. The 202 says the envelope was queued, not that anyone was emailed.
What the 202 does mean: the envelope exists in this workspace, it was draft, it has at least one signer, the workspace balance covered what the envelope costs, the workspace was under its monthly send ceiling, the row was locked, the persisted signers and fields were re-validated against the same envelope contract POST /envelopes enforces, readiness was computed from that locked snapshot, the status was moved to sending, and a durable envelope.send attempt committed. Immediate queue dispatch is best effort; the reconciler retries undispatched attempts. What it does not mean: nothing has been mailed, no signer token has been minted, no page has been rendered, and nothing has been charged.
States: draft -> sending (transient, editing locked) -> pending (out for signature: the worker charged the workspace, minted the signer tokens, rendered the pages, and mailed the invitations) -> completing -> completed. From pending an envelope may also reach declined, voided, or expired. If the send job exhausts its retries the envelope is returned to draft with a human-readable send error, tokens are reset, and any charge is refunded.
The credits. The envelope's price comes off the workspace inside the worker's claim transaction, together with the draft -> pending transition and a usage ledger row: one credit for the envelope, one for each signer who is not the sender, and one more when emailVerification is on. GET /envelopes/{envelopeId} reports the same number as creditCost. The balance check in this request is advisory: it fails fast on a balance that cannot cover the send but reserves nothing, so a send can still fail on credits later and be refunded.
Validation and readiness. Persisted envelope-contract validation runs first. Structural failures, including invalid field configuration, invalid signer defaults, and partial signer coverage, answer 422 invalid_envelope with contract issues. Readiness then owns missing or invalid sender values and the case where no signer owns any field; these answer 422 envelope_not_ready with readiness issues. Either locked refusal changes no status, queues no work, and spends nothing.
Polling recipe. Call GET /envelopes/{envelopeId} and watch status. sending means in flight; pending with a non-null sentAt means delivered to the signers; anything else is terminal. An envelope sitting in sending for more than a few minutes is stuck, not slow.
Webhook alternative. Subscribe to envelope.sent (the invitations went out), envelope.send_failed (the job gave up; the payload names the reason, recoveredStatus: "draft", and whether the credits were refunded), and envelope.completed (the executed PDF is ready to download).
Insufficient credits answers 402 insufficient_credits, with details.required and details.available, and changes nothing. Re-sending an already-sent envelope answers 400 invalid_status: the endpoint is a draft-only transition, and a retry of a send that already succeeded is not a second send. A workspace send ceiling answers 429 workspace_limit_exceeded with details.limit, which is a wait, not a fix to the envelope. A queue outage after the durable attempt commits does not change the 202 response or return the envelope to draft; reconciliation dispatches the same attempt later.
No request body. Honors Idempotency-Key; metered in the send rate bucket.
Request
- Base URL: https://inkseal.net/api/v1
- URL: https://inkseal.net/api/v1/envelopes/{envelopeId}/send
- Auth: HTTP bearer
Headers
Makes this mutation retry-safe. 1 to 255 printable ASCII characters (0x20 to 0x7e), trimmed before use. The key is scoped to the workspace and the credential that sent it. Reusing it with a different method, path, or payload answers 422 idempotency_key_reuse. A completed attempt replays its stored status and body with an Idempotent-Replay: true response header; 5xx, 429, and non-JSON answers leave the key retryable. A concurrent request holding the 90 second lease answers 409 idempotency_in_progress. Records are retained 24 hours.
Response
The envelope was claimed and queued (sending), or, on a workspace that requires a person to approve agent sends, parked for that approval (pending_approval). A parked send has queued nothing, emailed nobody and spent no credit. A retry of an unchanged draft returns the approval it already has. A retry after the draft was edited opens a new one and emails the owner again, because an approval covers only the revision the owner was shown.
Example response
{
"data": {
"id": "Jd3kR8sVqW2nX5cY7bLmP",
"status": "sending"
}
}Changes
No recorded changes to this operation across all 1 revision of this API.