Envelopes

Remind the signers of an envelope

Asks for reminders on an envelope that is out for signature, and reports what happened to every signer on it.

There is no per-signer targeting and no body. The endpoint takes no parameters at all: it runs the same reminder policy the scheduled sweep and the dashboard button run, and there is deliberately no way to name recipients or to bypass the cadence, because an API that could mail every signer on demand would be a spam engine with a key.

Throttling and cooldown. A signer is reminded only when the envelope is pending, has been sent, is not past its deadline, was sent at least one reminder interval ago (3 days), and has not been contacted within that same interval. Sequential envelopes hold everyone behind the first unsigned signer, and a sequential signer's clock starts at the hand-off (the last signature ahead of them), not at the envelope's send. The cadence slot is claimed with a compare-and-set before the message goes out, so an un-keyed retry inside the window finds the slot taken and reports reminder_not_due rather than mailing anyone twice. Two overlapping callers cannot both mail the same signer.

Every mailed link is freshly reissued through the canonical token strategy, which is why no raw token appears in the response: the link is bearer authority over one envelope and belongs only in the signer's mailbox. The caller gets a per-signer outcome keyed by public signer id instead.

Preconditions. Only pending is actionable. A draft, a finished envelope, or one past its deadline is refused whole with 409 invalid_state and details.status. expired there is derived from the deadline rather than read from the column, so an envelope the expiry sweep has not caught yet is still refused as expired. Note that void and the inbound actions report comparable refusals as 400 invalid_status; reminders use 409 invalid_state.

A 200 is not a promise that anyone was mailed: read summary and the per-recipient outcome. Honors Idempotency-Key; metered in the send rate bucket.

post/envelopes/{envelopeId}/reminders

Request

  • Base URL: https://inkseal.net/api/v1
  • URL: https://inkseal.net/api/v1/envelopes/{envelopeId}/reminders
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

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

One outcome per signer on the envelope, including the ones nothing was sent to, plus counts.

Example response

{
  "data": {
    "id": "Jd3kR8sVqW2nX5cY7bLmP",
    "status": "pending",
    "reminders": [
      {
        "id": "Sg2wY6nT4qV8mR1xK9bDz",
        "email": "dana@acme.test",
        "outcome": "sent",
        "reason": null
      },
      {
        "id": "Sg8pL3vB7nQ2xW6kT1yRc",
        "email": "sam@acme.test",
        "outcome": "skipped",
        "reason": "signer_not_notified"
      }
    ],
    "summary": {
      "sent": 1,
      "skipped": 1,
      "failed": 0
    }
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.