Send Postcard

POST

/post/postcards/send

Postcards

Supported File Types
We support PDF, docx and doc. Contact us to add support for any other file type. If you're using docx or doc files, you'll need to convert the file first using our uploads endpoint with the querystring parameter ?convert=post. e.g. POST /uploads?convert=post. This will return a URL to the converted pdf file that can be used in the /post/postcards/send endpoint.

Postcard File Options

Use existing URL

With this option, you can use an existing URL to a PDF document. For example, you might generate the pdf on your server.

For file_urls field. You can attach at least 1 and max of 2 PDF file urls.

Supply a single pdf with 2 pages (front and back)

Supply 2 urls to seperate PDFs

Upload File to Our Server

With this option, you can use the /uploads endpoint to upload the document. The /uploads endpoint returns a URL that can be used in the /post/postcards/send endpoint.

Request Example

Shell

JavaScript

Java

Swift

curl --location --request POST 'https://rest.clicksend.com/v3/post/postcards/send' \
--header 'Content-Type: application/json' \
--data-raw '{
    "file_urls": [
        "https://s3-ap-southeast-2.amazonaws.com/clicksend-api-downloads/_public/_examples/a5_front.pdf",
        "https://s3-ap-southeast-2.amazonaws.com/clicksend-api-downloads/_public/_examples/a5_back.pdf"
    ],
    "recipients": [
        {
            "address_city": "City",
            "address_country": "AU",
            "address_line_1": "Address 1",
            "address_line_2": "",
            "address_name": "John Smith",
            "address_postal_code": "123456",
            "address_state": "State",
            "custom_string": "Custom abc123",
            "return_address_id": 1
        }
    ]
}'

Response Example

{
    "data": {
        "_currency": {
            "currency_name_long": "Australian Dollars",
            "currency_name_short": "AUD",
            "currency_prefix_c": "c",
            "currency_prefix_d": "$"
        },
        "queued_count": 1,
        "recipients": [
            {
                "_api_username": "johndoe",
                "_file_url": "https://rest.clicksend.com/files/6A559A74-486D-4012-84D7-F3FE11904CB1.pdf",
                "_return_address": {
                    "address_city": "Perth",
                    "address_country": "AU",
                    "address_line_1": "123 Test St",
                    "address_line_2": "",
                    "address_name": "John Doe",
                    "address_postal_code": "6000",
                    "address_state": "WA",
                    "return_address_id": 1,
                    "user_id": 1
                },
                "address_city": "CITY",
                "address_country": "AU",
                "address_line_1": "Address 1",
                "address_line_2": "",
                "address_name": "John Smith",
                "address_postal_code": "123456",
                "address_state": "State",
                "date_added": 1482473172,
                "ip_address": "127.0.0.1",
                "letter_file_name": "6A559A74-486D-4012-84D7-F3FE11904CB1.pdf",
                "message_id": "C8CAA97A-905A-4A31-99CB-A92C7BA05A97",
                "post_price": 11,
                "priority": 32,
                "return_address_id": 1,
                "schedule": 1482473172,
                "source": ".rest.v3",
                "status": "SUCCESS",
                "subaccount_id": 13,
                "user_id": 1
            }
        ],
        "total_count": 1,
        "total_price": 11
    },
    "http_code": 200,
    "response_code": "SUCCESS",
    "response_msg": "Postcard queued for delivery."
}

Request

Body Params application/json

file_urls

array

required

Postcard file urls. You can submit max 2 file urls.

recipients

array

required

Your recipients.

Examples

Responses

🟢200OK

application/json

Body

object {0}

Calculate Pricing

Get Country Pricing