Postcards API

The Oppizi Postcards API allows you to send physical postcards to your customers. The API integrates with ClickSend and H-Pod services to handle the printing and delivery of postcards.

Note: Currently, this service is only available for addresses within the European Union.

Send postcard

Send a physical postcard to one or more recipients.

Endpoint

POST https://developer-api.oppizi.com/postcards

Parameters

fileUrls required
Array of URLs to PDF files containing the postcard design. Currently supports one URL.

recipients required
Array of recipient objects containing the following fields:

addressName required - Full name of the recipient
addressLine1 required - First line of the address
addressLine2 optional - Second line of the address
addressCity required - City
addressState required - State/Province
addressPostalCode required - Postal/ZIP code
addressCountry required - Two-letter country code (e.g., 'GB' for United Kingdom)

Note: Currently only EU addresses are supported.

Request body

{
  "fileUrls": ["https://example.com/postcard.pdf"],
  "recipients": [
    {
      "addressName": "John Smith",
      "addressLine1": "42 Oxford Street",
      "addressLine2": "Flat 3B",
      "addressCity": "London",
      "addressState": "Greater London",
      "addressPostalCode": "W1D 2DZ",
      "addressCountry": "GB"
    }
  ]
}

Response

{
  "success": true,
  "data": {
    "JobGuid": "job-guid",
    "submissionId": "submission-id",
    "status": "status",
    "estimatedCompletionDate": "date"
  }
}

Example

fetch('https://developer-api.oppizi.com/postcards', {
  method: 'POST',
  headers: new Headers({
    'Content-Type': 'application/json',
    Authorization: 'Bearer YOUR_SECRET_KEY',
  }),
  body: JSON.stringify({
    fileUrls: ['https://example.com/postcard.pdf'],
    recipients: [
      {
        addressName: 'John Smith',
        addressLine1: '42 Oxford Street',
        addressLine2: 'Flat 3B',
        addressCity: 'London',
        addressState: 'Greater London',
        addressPostalCode: 'W1D 2DZ',
        addressCountry: 'GB'
      }
    ]
  }),
});

Error Response

{
  "success": false,
  "error": "Failed to create postcard"
}

Last updated on May 28, 2025