We have created an OpenAPI 3 definition of our API. View our API documentation on SwaggerHub and you can get more information and try the API out. You can also view our OpenAPI (YAML) definition on GitHub.

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.

UML structure

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 tracking ID 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."
                        }