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

Authentication

Each endpoint requires you to be authenticated. You have to create an API-key from your My Account page. Please keep in mind that you can only have one API-key active at a time. Whenever you create a new API-key, your old one will be invalid, so store your generated API-key somewhere safe. 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.
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).

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\"}"

201 Created - Response:

{
                        "success": true,
                        "msg": {
                        "id": 123,
                        "name": "Newsletter"
                        }
                        }
                    

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 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": {
                        "token": "fbAQfWDabnHgQNwf4CFZ.png",
                        "url": "https://pastepixel.com/image/fbAQfWDabnHgQNwf4CFZ.png"
                        }
                        }
                    

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 128).

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/"
                        }
                        }
                    

Delete

To delete a trackable URL, you send a DELETE request to /mail-tracking/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 /mail-tracking/url/<ID>

$ curl -X DELETE "https://pastepixel.com/api/v1/mail-tracking/url/235?key=<KEY>"

200 OK - Response

{
                        "success": true,
                        "msg": "Trackable url successfully deleted."
                        }