Idempotency Keys - Direct Mail API

Idempotent Requests

Our API supports an optional idempotency key for safely retrying requests without performing a repeat operation. If a request is idempotent, we will return the original response body with a 409 HTTP status. We match the body of the request so only identical requests will be treated as idempotent.

How Idempotency Works

Idempotency keys help ensure that API requests are processed exactly once, even if they are sent multiple times.

  • To perform an idempotent request, the optional header X-Idempotency-Key: {key} must be set. The key may be anything you like, but we recommend a UUID with a high level of entropy to avoid collisions. Idempotency keys must be between 10 and 1024 characters in length.
  • Only POST requests may be idempotent. Setting an idempotency key for GET will have no effect.
  • We store idempotency keys for 24 hours. A request made after this time will be treated as a new request, and the operation will be performed normally.

Example Request

Here's an example of creating a letter with an idempotency key:

[POST]
https://ca.stannp.com/api/v1/letters/create

Request Example

        curl "https://ca.stannp.com/api/v1/letters/create" \
-u {API_KEY}: \
-H "X-Idempotency-Key: e367c03e-3082-4c8e-b647-d6810761dcd4" \
-d "test=true" \
-d "background=https://www.stannp.com/assets/samples/letter-heading.webp" \
-d "pages=Hello {firstname}, <br><br>This is my first letter." \
-d "recipient[title]=Mr" \
-d "recipient[firstname]=John" \
-d "recipient[lastname]=Smith" \
-d "recipient[address1]=123 Sample Street" \
-d "recipient[address2]=Sampleland" \
-d "recipient[town]=Sampletown" \
-d "recipient[postcode]=AB12 3CD" \
-d "recipient[country]=CA"

Response Example

{
  "success": true,
  "data": {
    "pdf": "https://www.stannp.com/assets/samples/letter-sample.pdf",
    "id": "0",
    "created": "2020-12-17T15:42:22+00:00",
    "format": "letter",
    "cost": "0.78",
    "status": "test"
  }
}

Response Codes

When using idempotency keys, you may receive different HTTP status codes:

Status Codes

Status CodeDescription
200 OKRequest processed successfully (first time).
409 ConflictIdempotent request - returning original response.