Prerequisites:
You will need to get the following information from Opensend Dashboard:
- Webhook URL: https://api.opensend.com/postal/postcard
- Integration ID: Go to the “Postcard configuration” tab and copy it from there
- Postal API key:
- Go to Settings
- Click on "API key"
- Click "Create New API key"
- Add the Key Name and description
- Select "Postal" under Scopes
- Click "Create"
- Copy and save the API key
Guide on direct API Integration:
- API endpoint: https://api.opensend.com/postal/postcard
- Headers:
x-api-key:
Postal API key you copied from the dashboard
Content-Type: application/json - Input:
Required body:
{
"integration_id": "<INTEGRATIONID>",
"email": "<email>"
}
Optional body:
{"contact_details":
{
"zip": <zip>,
"city": <city>,
"state": <state>,
"address": <address>,
"last_name": <last_name>,
"first_name": <first_name>,
"phone_number": <phone_number>,
"company_name": <company_name>,
"job_title": <job_title>
}
}
Note: any optional data will overwrite Opensend enriched data from email such as username, address, ... - Sample:
curl -X POST 'https://api.opensend.com/postal/postcard' -H 'x-api-key: <API-KEY>' -H "Content-Type: application/json" -d '{"integration_id": "<INTEGRATIONID>", "email": "<email>", "contact_details": <contact_details>}' - Response:
{'request_id': <request_id>, 'status': 'success'}
- Please note the following characteristics for Postal:
- The same contact will not be able to receive a postcard request within 48 hours from creation time on the Opensend dashboard or within 24 hours from the updated time(i.e. status change from Ready to Printing to Delivering etc) on our Postal Mail service
- Requests received within this time where we already received a request for a certain contact will not be processed. (400 return code)
-
- This rule does not apply if the user changes templates (HTML or PDF) - If there is a template change, the contact we received can again receive another template/different postcard
- If you want to ignore/override these rules, update the payload to:
{
"integration_id": "<INTEGRATIONID>",
"email": "<email>",
"force_send": true
}
Check postal request status:
- API endpoint: https://api.opensend.com/postal/postal_status
- Headers:
x-api-key:
Postal API key you copied from the dashboard
Content-Type: application/json - Input:
{"integration_id": "<INTEGRATIONID>", "request_id": "<request_id>"} - Sample:
curl -X POST 'https://api.opensend.com/postal/postal_status' -H 'x-api-key: <API_KEY>' -H "Content-Type: application/json" -d '{"integration_id": "<INTEGRATIONID>", "request_id": "<request_id>"}' - Response:
{'status': 'success', 'data': <postcard_detail>}