Postcards API

The Oppizi Postcards API allows you to send physical postcards to your customers.

Currently, this service is only available for addresses within the European Union. Americas and Asia are not supported yet.

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 - Full country name (e.g., 'FRANCE')

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": "GREAT BRITAIN"
    }
  ]
}

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_CLIENT_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: 'GREAT BRITAIN',
      },
    ],
  }),
});

Error Response

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