Introduction
Welcome to the official PastePixel API documentation. In order to use the PastePixel API you must have a premium or early bird account. Feel free to check out our pricing page to see all our plans.
The latest version of the API is v1 currently. Using this API, you are able to
integrate PastePixel into your own applications and automatically track mails. This API allows you
to create new mail trackings, tracking pixels and trackable URLs. We also provide endpoint to
delete your mail tracking or a trackable URL.
How to create a mail tracking with a pixel and trackable urls? Structurally, you first create a new mail tracking with a name, for example "Newsletter". This will then be shown on your dashboard. Then, you can add a tracking pixel to your mail tracking. This will give you an URL that you then can embed in your e-mails. Note that a mail tracking can only have zero or one tracking pixel. Then you can add up to twenty trackable URLs to your mail tracking. See the shown figure for a generic UML diagram of how a mail tracking structurally is composed.
This API uses the principles of a REST-API, meaning that you should use certain HTTP-methods, like GET, POST, DELETE and PUT, on our endpoints. Also notice that some endpoints require you to provide a JSON-body.
The base URL of this API is: https://pastepixel.com/api/v1. The rate limit is set to
30 requests per minute.
Authentication
Each endpoint requires you to be authenticated. You have to create an API-key from your My Account page. You authenticate yourself by adding a "key" parameter to each endpoint with as value your API-key. This can be seen in all examples.
Please prevent calling our API from your public javascript files, as this allows users on your website to see your API-key.
POST /mail-tracking
$ curl -X POST https://pastepixel.com/api/v1/mail-tracking?key=<KEY> -H "Content-type: application/json" -d "{\"name\":\"Newsletter\"}"Response codes
Our API uses the following response codes:
| Code | Name | Reason |
|---|---|---|
| 200 | OK | Your request has succeeded. |
| 201 | Created | A new entity has successfully been created. |
| 400 | Bad request | Missing data that you should provide. |
| 401 | Unauthorized | Your API-key is invalid or you are trying to create/delete/edit an entity for an account that isn't yours. |
| 403 | Forbidden | You have exceeded your plan. For example, the number of mail tracking that you have created in a day. |
| 429 | Too many requests | You've succeeded the rate limit of 30 requests per minute. Wait one minute before performing another request. |
| 500 | Internal server error | We experienced some kind of unexpected server-side error. Please contact us if you keep getting this error. |
Mail tracking
A mail tracking is the entity with a name that can 'own' a tracking pixel and zero or more trackable URLs. All created mail tracking can be seen on your dashboard.
Create
To create a new mail tracking, you send a POST request to the endpoint: /mail-tracking.
You should provide a JSON-body with the following attributes:
JSON-body attributes
name required
The name of your new mail tracking. This name can be found on your dashboard after creating the
mail tracking. Type: String (max. length: 64).
enabled
Whether data collection is paused or not. When disabled, your tracking pixel and URLs won't
collect any data. You can enable data tracking later on, for example sometime after you have
sent out your email. Type: Boolean (defaults to true).
uniqueOpensOnly
Whether to collect only unique data. This is based on the IP-address of the tracked data, so a
tracking pixel can then track an IP-address at most one time. Important: If you set this value
to true, then trackIpAddresses must also be set to true. Type: Boolean
(defaults to false).
trackIpAddresses
Privacy setting on whether the tracking pixel and URLs should track IP-addresses. When disabled,
the mail tracking page also won't render the "Location" chart. This setting cannot be changed
after creating the mail tracking. Important: When this is set to false, then
uniqueOpensOnly cannot be set to true. Type: Boolean (defaults to true).
trackUserAgents
Privacy setting on whether the tracking pixel and URLs should track user-agents. When disabled,
the mail tracking page also won't render the "Devices" chart. This setting cannot be changed
after creating the mail tracking. Type: Boolean (defaults to true).
trackDateTimes
Privacy setting on whether the tracking pixel and URLs should track the date/times on which
they got triggered. When disabled, the mail tracking page also won't show the "Times opened" and
"Time of day" charts. This setting cannot be changed after creating the mail tracking.
Type: Boolean (defaults to true).
Returns
Returns a 201 Created response with a JSON-body that contains the ID of your newly created mail tracking. This ID can later be used to delete your mail tracking.POST /mail-tracking
$ curl -X POST "https://pastepixel.com/api/v1/mail-tracking?key=<KEY>" -H "Content-type: application/json" -d "{\"name\":\"Newsletter\", \"enabled\":true, \"uniqueOpensOnly\":false, \"trackIpAddresses\":true, \"trackUserAgents\":true, \"trackDateTimes\":true}"201 Created - Response:
{
"success": true,
"msg": {
"id": 465,
"name": "Newsletter"
}
}
Get information
To retrieve information about a mail tracking and its pixel and tracking URLs, you send a GET
request to the endpoint: /mail-tracking/<ID>, where ID is the ID of an existing
mail tracking.
Returns
Returns a 200 OK response with a JSON-body that contains information about the mail trackingID is the ID of the mail tracking.
created is the timestamp of the creation date of the mail tracking (milliseconds since epoch).
url is the URL to the PastePixel dashboard page.
name is the name of the mail tracking.
enabled is the indication on whether data collection is active or paused.
uniqueOpensOnly is the indication on whether to collect unique opens only (IP-address based).
privacySettings is an object with the privacy settings set the for mail tracking
(immutable).
trackingPixel is an object with pixel information or null if that pixel has not
been created yet. Contains the same fields as
tracking pixel information.
trackableUrls is an array with objects containing trackable URL information.
Contains the same fields as trackable URL information.
GET /mail-tracking/<ID>
$ curl -X GET "https://pastepixel.com/api/v1/mail-tracking/465?key=<KEY>"200 OK - Response
{
"success": true,
"msg": {
"id": 465,
"created": 1611599175410,
"mailTrackingUrl": "https://pastepixel.com/tracking/465",
"name": "Newsletter",
"enabled": true,
"uniqueOpensOnly": false,
"privacySettings": {
"trackIpAddresses": true,
"trackUserAgents": true,
"trackDateTimes": true
},
"trackingPixel": {
"id": 123,
"created": 1611599175410,
"token": "fbAQfWDabnHgQNwf4CFZ.png",
"url": "https://pastepixel.com/image/fbAQfWDabnHgQNwf4CFZ.png",
"timesOpened": 50
},
"trackableUrls": {[
"id": 756,
"created": 1611599175410,
"token": "fbAQfWDabnHgQNwf4Cqw",
"trackableUrl": "https://pastepixel.com/url/fbAQfWDabnHgQNwf4Cqw",
"originalUrl": "https://my-website.com/",
"timesOpened": 50
]}
}
}
Delete
To delete an existing mail tracking, you send a DELETE request to the endpoint: /mail-tracking/<ID>,
where you use to ID of the mail tracking that you want to delete.
Returns
Returns a 200 OK response with a JSON-body indicating that the mail tracking has successfully been deleted.DELETE /mail-tracking
$ curl -X DELETE "https://pastepixel.com/api/v1/mail-tracking/<ID>?key=<KEY>"200 OK - Response
{
"success": true,
"msg": "Mail tracking successfully deleted."
}
Tracking pixel
A tracking pixel is the 'image' that you put in your sent e-mails. This pixel allows you to track your e-mail. A tracking pixel belongs to one mail tracking and has a unique token.
Create
To create a new tracking pixel you send a POST request to the endpoint:
/mail-tracking/<ID>/pixel, where ID is the ID of an existing mail tracking that
has no pixel yet.
Returns
Returns a 201 Created response with a JSON-body that contains the ID, unique token of your tracking pixel and the URL of the tracking pixel, that you should embed as an image in your outgoing e-mails.POST /mail-tracking/<ID>/pixel
$ curl -X POST "https://pastepixel.com/api/v1/mail-tracking/123/pixel?key=<KEY>"201 Created - Response
{
"success": true,
"msg": {
"id": 144,
"token": "fbAQfWDabnHgQNwf4CFZ.png",
"url": "https://pastepixel.com/image/fbAQfWDabnHgQNwf4CFZ.png"
}
}
Get information
To retrieve information about a tracking pixel, you send a GET request to the endpoint:
/pixel/<ID>, where ID is the ID of an existing tracking pixel.
Returns
Returns a 200 OK response with a JSON-body that contains information about the tracking pixel.ID is the ID of the tracking pixel.
created is the timestamp of the creation date of the pixel (milliseconds since epoch).
token is the unique token of the tracking pixel.
url is the image URL of the tracking pixel (contains the token).
timesOpened is the number of times the tracking pixel has been triggered, without the blacklisted IP-addresses.
mailTrackingId is the ID of the parent mail tracking.
mailTrackingUrl is the URL of the mail tracking where you can view all data and charts collected by the pixel.
GET /pixel/<ID>
$ curl -X GET "https://pastepixel.com/api/v1/pixel/123?key=<KEY>"200 OK - Response
{
"success": true,
"msg": {
"id": 123,
"created": 1611599175410,
"token": "fbAQfWDabnHgQNwf4CFZ.png",
"url": "https://pastepixel.com/image/fbAQfWDabnHgQNwf4CFZ.png",
"timesOpened": 50,
"mailTrackingId": 465,
"mailTrackingUrl": "https://pastepixel.com/tracking/465"
}
}
Get data
To retrieve paginated tracked data that is collected by your tracking pixel, you send a GET request
to the endpoint: /pixel/<ID>/data?offset=<OFFSET>&limit=<LIMIT>.
ID is the ID of an existing tracking pixel. Data is sorted from new-old, so the first record is the
most recent tracked data.
URL parameters
offset
Offset for the paginated result. With an offset of 0, you start at the most recent data.
Type: Integer (min: 0, max: 45000, defaults to 0).
limit
Limit for the paginated result. This is the maximum number of results on the requested page.
Type: Integer (min: 1, max:
100, defaults to 10).
Returns
Returns a 200 OK response with a JSON-body that contains your tracked data.timesOpened is the total count of the tracked data, this takes blacklisted IP-addresses in account.
offset is the given offset of the page.
limit is the max. number of results on the page.
data is an array that contains all tracked data on the given page.
date is the timestamp of when the data was tracked (ms since epoch). This can be null if date & time tracking is off.
ipAddress is the tracked IP-address. This can be null if IP-address tracking is off.
userAgent is the tracked user-agent. This can be null if user-agent tracking is off.
customData is the tracked custom data. If there was no custom data, then this property is omitted.
GET /pixel/<ID>/data?offset=<OFFSET>&limit=<LIMIT>
$ curl -X GET "https://pastepixel.com/api/v1/pixel/123/data?offset=3&limit=50&key=<KEY>"200 OK - Response
{
"success": true,
"msg": {
"timesOpened": 200,
"offset": 3,
"limit": 50,
"data": [
{
"date": 1631113189648,
"ipAddress": "255.255.255.255",
"userAgent": "Mozilla/5.0 ...",
"customData": "My custom data"
},
{
"date": 1631113195648,
"ipAddress": "255.255.255.255",
"userAgent": "Mozilla/5.0 ...",
},
...
]
}
}
Trackable URL
A trackable URL is an URL that you can track, just like tracking pixels. Whenever someone opens the URL it refers to the website that you have entered. A mail tracking can have up to 20 trackable URLs.
Create
To create a trackable URL, you send a POST request to /mail-tracking/<ID>/url,
where ID is the ID of an existing mail tracking, that has less than 20 trackable URLs. You should
also provide a JSON-body with the following attribute:
JSON-body attributes
url required
The full URL of the web page that the trackable URL should redirect to. Type: String (max. length 512).
Returns
Returns a 201 Created response with a JSON-body containing the trackable URL. This trackable URL is the URL that you should put in your e-mail instead of the URL where is redirects to. The JSON-body also contains the unique ID of the trackable URL, this ID can be used to delete a trackable URL.POST /mail-tracking/<ID>/url
$ curl -X POST "https://pastepixel.com/api/v1/mail-tracking/4/url?key=<KEY>" -H "Content-type: application/json" -d "{\"url\":\"https://mywebsite.com/\"}"201 Created - Response
{
"success": true,
"msg": {
"id": 235,
"token": "ZHMhkAbySWXFQqdpB7PQ",
"trackableUrl": "https://pastepixel.com/url/ZHMhkAbySWXFQqdpB7PQ",
"originalUrl": "https://mywebsite.com/"
}
}
Get information
To retrieve information about a tracking url, you send a GET request to the endpoint:
/url/<ID>, where ID is the ID of an existing tracking url.
Returns
Returns a 200 OK response with a JSON-body that contains information about the tracking url.ID is the ID of the tracking url.
created is the timestamp of the creation date of the URL (milliseconds since epoch).
token is the unique token of the tracking url.
trackableUrl is the URL of the tracking link (contains the token), this URL redirects to the originalUrl and tracks its opens.
originalUrl is the URL where the tracking URL redirects to.
timesOpened is the number of times the tracking URL has been opened, without the blacklisted IP-addresses.
mailTrackingId is the ID of the parent mail tracking.
mailTrackingUrl is the URL of the mail tracking where you can view all data and charts collected by the tracking url.
GET /url/<ID>
$ curl -X GET "https://pastepixel.com/api/v1/url/756?key=<KEY>"200 OK - Response
{
"success": true,
"msg": {
"id": 756,
"created": 1611599175410,
"token": "fbAQfWDabnHgQNwf4Cqw",
"trackableUrl": "https://pastepixel.com/url/fbAQfWDabnHgQNwf4Cqw",
"originalUrl": "https://my-website.com/",
"timesOpened": 89,
"mailTrackingId": 465,
"mailTrackingUrl": "https://pastepixel.com/tracking/465"
}
}
Get data
To retrieve paginated tracked data that is collected by your trackable URL, you send a GET request
to the endpoint: /url/<ID>/data?offset=<OFFSET>&limit=<LIMIT>.
ID is the ID of an existing trackable URL. Data is sorted from new-old, so the first record is the
most recent tracked data.
URL parameters
offset
Offset for the paginated result. With an offset of 0, you start at the most recent data.
Type: Integer (min: 0, max: 45000, defaults to 0).
limit
Limit for the paginated result. This is the maximum number of results on the requested page.
Type: Integer (min: 1, max:
100, defaults to 10).
Returns
Returns a 200 OK response with a JSON-body that contains your tracked data.timesOpened is the total count of the tracked data, this takes blacklisted IP-addresses in account.
offset is the given offset of the page.
limit is the max. number of results on the page.
data is an array that contains all tracked data on the given page.
date is the timestamp of when the data was tracked (ms since epoch). This can be null if date & time tracking is off.
ipAddress is the tracked IP-address. This can be null if IP-address tracking is off.
userAgent is the tracked user-agent. This can be null if user-agent tracking is off.
customData is the tracked custom data. If there was no custom data, then this property is omitted.
GET /url/<ID>/data?offset=<OFFSET>&limit=<LIMIT>
$ curl -X GET "https://pastepixel.com/api/v1/url/756/data?offset=0&limit=10&key=<KEY>"200 OK - Response
{
"success": true,
"msg": {
"timesOpened": 20,
"offset": 0,
"limit": 10,
"data": [
{
"date": 1631113189648,
"ipAddress": "255.255.255.255",
"userAgent": "Mozilla/5.0 ...",
"customData": "My custom data"
},
{
"date": 1631113195648,
"ipAddress": "255.255.255.255",
"userAgent": "Mozilla/5.0 ...",
},
...
]
}
}
Delete
To delete a trackable URL, you send a DELETE request to /url/<ID>,
where ID is the ID of the trackable URL that you want to delete.
Returns
Returns a 200 OK response with a JSON-body indicating that the trackable URL has successfully been deleted.DELETE /url/<ID>
$ curl -X DELETE "https://pastepixel.com/api/v1/url/235?key=<KEY>"200 OK - Response
{
"success": true,
"msg": "Trackable url successfully deleted."
}