Postcards

`POST /api/v1/postcards/send`

Send one or many postcards with custom HTML. Requires a valid API key.

Request body


{
  "from": {
    "firstName": "Avery",
    "lastName": "Lane",
    "line1": "123 Main St",
    "city": "Denver",
    "stateProvince": "CO",
    "postalCode": "80202",
    "country": "US"
  },
  "to": [
    {
      "firstName": "Jordan",
      "lastName": "Parker",
      "line1": "456 Ocean Ave",
      "city": "San Francisco",
      "stateProvince": "CA",
      "postalCode": "94105",
      "country": "US"
    }
  ],
  "frontHtml": "<!doctype html>...",
  "backHtml": "<!doctype html>...",
  "templateContext": {
    "front": { "templateId": 101, "templateName": "Summer Front" },
    "back": { "templateId": 202, "templateName": "Photo Back" }
  }
}

Validation highlights

to supports 1-500 recipients.
frontHtml and backHtml are required.
Each HTML string max length: 2,000,000.
Countries must be valid ISO alpha-2 codes.

Billing behavior

If user has enough tokens, tokens are consumed.
If not enough tokens and a saved card exists, card is charged.
Partial failures automatically trigger refund/credit compensation for failed recipients.

Success response


{
  "success": true,
  "batchId": "uuid",
  "recipientCount": 1,
  "persistedSendIds": [1234],
  "failedCount": 0,
  "failedRecipients": [],
  "billing": {
    "mode": "token",
    "amountCents": 0,
    "tokenCount": 1,
    "stripePaymentIntentId": null
  }
}

Common errors

401: missing/invalid API key
402: insufficient payment method or token race condition
400: payload validation issues
502: downstream print provider errors

`POST /api/v1/postcards/send`

Send one or many postcards with custom HTML. Requires a valid API key.

Request body


{
  "from": {
    "firstName": "Avery",
    "lastName": "Lane",
    "line1": "123 Main St",
    "city": "Denver",
    "stateProvince": "CO",
    "postalCode": "80202",
    "country": "US"
  },
  "to": [
    {
      "firstName": "Jordan",
      "lastName": "Parker",
      "line1": "456 Ocean Ave",
      "city": "San Francisco",
      "stateProvince": "CA",
      "postalCode": "94105",
      "country": "US"
    }
  ],
  "frontHtml": "<!doctype html>...",
  "backHtml": "<!doctype html>...",
  "templateContext": {
    "front": { "templateId": 101, "templateName": "Summer Front" },
    "back": { "templateId": 202, "templateName": "Photo Back" }
  }
}

Validation highlights

to supports 1-500 recipients.
frontHtml and backHtml are required.
Each HTML string max length: 2,000,000.
Countries must be valid ISO alpha-2 codes.

Billing behavior

If user has enough tokens, tokens are consumed.
If not enough tokens and a saved card exists, card is charged.
Partial failures automatically trigger refund/credit compensation for failed recipients.

Success response


{
  "success": true,
  "batchId": "uuid",
  "recipientCount": 1,
  "persistedSendIds": [1234],
  "failedCount": 0,
  "failedRecipients": [],
  "billing": {
    "mode": "token",
    "amountCents": 0,
    "tokenCount": 1,
    "stripePaymentIntentId": null
  }
}

Common errors

401: missing/invalid API key
402: insufficient payment method or token race condition
400: payload validation issues
502: downstream print provider errors