Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Server Endpoints
Environment | URL |
---|---|
Beta
api-beta.zappost.com
production
api.zappost.com
The ZAPI requires authentication credentials to be provided with every HTTP request. Applications can authenticate with the API using basic HTTP authentication over SSL. To obtain the required credentials, please visit the 'settings' page in the ZAP APP under 'API Consumers'.
To authenticate, use basic HTTP authorization, where the API key of the application is the API Key and the API password is the API password in the UI. Some HTTP clients allow for basic authentication by including the key:password in the URL hostname. For example:
POST 45634643FGDFGFDG:hfcdethuzzjhg54@'https://api.zappost.com/api/'
If your HTTP client does not support basic authentication using this method, you can provide the credentials in the Authorization header field. To do so, join the API key and API password with a single colon (:). Then, encode the resulting string in base64 representation and prepend the base64-encoded string with "Basic" and a space. The resulting string should be included in the Authorization header field, as shown below:
Authorization: Basic NDQ3OGViN2FjMTM4YTEzNjg1MmJhYmQ4NjE5NTZ...=
It's important to keep the authentication credentials secure and not share them with unauthorized users. Make sure to store the credentials securely and not hardcode them in your application code or config files.
This document is intended to serve as an integration guide for anyone working with the ZAP~POST API as part of their direct mail workflow.
Welcome to the documentation for The ZAP~POST API (ZAPI)! Our API allows you to easily integrate direct mail campaigns into your application or workflow, automating the process of sending physical mail to your customers or prospects. With our API, you can quickly and easily create and send Postcards and other direct mail pieces called ZAPs.
Our ZAP POST Platform is designed to be flexible and easy to use, allowing you to customize your direct mail campaigns to meet the specific needs of your business. You can choose from a variety of sizes and formats for your direct mail pieces, and our API supports both individual and batch submissions.
In this documentation, you will find everything you need to get started with our API, including detailed API reference documentation, sample code snippets, and step-by-step tutorials to help you integrate our API into your application. Whether you're a developer building a new application or a marketer looking for an easier way to manage your direct mail campaigns, our API has everything you need to simplify and streamline your direct mail processes.
Campaigns allow users to send direct mail based on a real time events or actions which is specific to an individual customer. Each campaign has it's own configuration of required data in order to trigger a relevant ZAP for example a an abandoned basket campaign might require a session ID and a list of products but a customer birthday might only expect the recipient info and a birthday date
Users can list all campaigns available in ZAP POST. This will provide some basic campaign information such as the name and current status.
Users can also look up a specific campaign which will include more detailed information regarding the custom field configuration on the campaign such as expected values and validation expressions.
Most of the time you'll be listing campaigns to find the ID of the appropriate campaign you wish to create a submission against or to check the progress of a historically created submission.
Expected values are configured against fields on the campaign. If any expected values exist, then the API will only accept the values within that list. For example, I might configure a DayOfTheWeek field on my campaign. If I do this I may configure the expected values "Monday","Tuesday","Wednesday","Thursday","Friday","Saturday" and "Sunday". This is intended to provide some basic validation to clients configuring their campaigns.
Validations are regex expressions and paired messages. When a record is received against the campaign ZAP will validate that all validation expressions are passed. If any fail, a list of errors will be compiled with the relevant message configured for the validation expression. This piece of functionality provides more advanced validation as the regex expressions can get quite complex.
Returned ZAPs are mailings that were successfully sent but returned because the carrier couldn't physically deliver them for some reason. We will log any ZAPs returned as well as the reason they weren't delivered if the carrier provides one. This information can be retrived on a submission level via the following endpoint.
Schedule Sends, are the dates available for users to pair their submissions with. A submission that's paired with a scheduled send, will be mailed on that date landing with customers the day after.
You can list the current scheduled sends available in ZAP POST via the API and use the ID to pair the submission with the relevant send date
The team are constantly adding new dates to our pool of available sends, make sure you check this endpoint frequently is your campaigns are most effective when delivered close to a particular future date.
Rejected records are the records which were sent to ZAP POST via the API which have subsequently failed our data cleansing process. Data cleansing is the process of checking the accuracy of records using the Postcode Address File as well as a database of Deceased or Gone Away recipients. Data filtering, PAF check and data cleansing is all included as part of the ZAP~POST process.
As part of the data cleansing process, we provide all clients with a 'Cleanse Report' at the end of each campaign. This report will highlight any records from the original submission that failed a PAF, deceased or gone away check.
Success
Success
Success
Success
Success
A common use case for the records endpoint would be to submit an individual record when a basket is abandoned for an e-com journey or for a customer quote request
Its very important to note that low volumes of records submitted to the ZAPI will be compiled into larger submissions at the end of each day. This is to reduce the total volume of submissions created against a campaign and make monitoring a much easier task for regularly scheduled campaigns. This means you won't be able to query for any updates on records submitted until the day after submission when they've been batched.
A common use case for this endpoint would be when adding a collection of related records such as a group of renewal reminders for a monthly send or a list of lapsed customers
Users can also list any submissions that exist against a campaign or list submissions actively working through the ZAP flow before being sent.
Any records or submissions sent to the ZAP API will be automatically included on the soonest available scheduled send if one is not specified. Unless you wish to use a specific send in the future it's most likely you don't need to specify the scheduled send on the request.
When creating a submission users have the option to set 'OnlyValidRecords' to true or false. When true the records in the submission will only be accepted if every record is valid. If 'OnlyValidRecords' is set to false, then any records that pass validation will be accepted and any that fail will not and will be returned in the usual response format detailing the validation failures.
Expected values are configured against fields on the campaign. If any expected values exist, then the API will only accept the values within that list. For example, I might configure a DayOfTheWeek field on my campaign. If I do this I may configure the expected values "Monday","Tuesday","Wednesday","Thursday","Friday","Saturday" and "Sunday". Any records that fail because of an expected value will have the list of valid values returned in the error provided on submission.
Validations are regex expressions and paired messages. When a record is received against the campaign ZAP will validate that all validation expressions are passed. If any fail, a list of errors will be compiled with the relevant message configured for the validation expression. This piece of functionality provides more advanced validation as the regex expressions can get quite complex.
The custom data object is used for custom fields that are created for a campaign. Each customField property should match the 'label' given to the matching custom field. Querying the GET campaign/{CampaignId} endpoint will return a list of all custom fields for the campaign.
- List campaigns and view campaign specific information or configuration
- List the current scheduled send dates available in ZAP POST
- Push data to the ZAP API and trigger your direct mail sends
- Look up details for any records that have failed our data cleansing process
- List any ZAPs that were unable to be posted and why
Submissions are collections of records that are submitted against a campaign. The records are made up of the required recipient information and the relevant campaign specific fields that have been configured in the The POST endpoints allow users to submit either an entire self contained collection of records intended to be sent together on a specific date or they can submit individual records after an appropriate event has occurred.
Property | Mandatory | ErrorMessage | Max Text Length |
---|
CustomerId | Yes | Must be unique | 100 |
No | be in standard email address format. | 255 |
Salutation | No | Must be alphanumeric, full-stop and space only. | 35 |
Firstname | Yes | Must be alphanumeric, space, -, (, ), full-stop and ' only. | 35 |
Surname | Yes | Must be alphanumeric, space, -, (, ), full-stop and ' only. | 35 |
Address1 | Yes | Must contain alphanumeric, space, ', ., &, -, /, \, ), ( and , characters only. | 35 |
Address2 | No | Must contain alphanumeric, space, ', ., &, -, /, \, ), ( and , characters only. | 35 |
Address3 | No | Must contain alphanumeric, space, ', ., &, -, /, \, ), ( and , characters only. | 35 |
City | No | Must contain alphanumeric, space, ', ., &, -, /, \ and , characters only. | 255 |
Postcode | Yes | Must be alphanumeric, - and spaces only. | 15 |
Country | Yes | Must contain letters, space, -, (, ), full-stop, & and ' only. | 255 |
Currency | No | Must contain letters only. | 3 |
Language | No | Must contain letters only. | 10 |
Success
Success
For more information visit the documentation
Success
For more information visit the documentation
Success