Creating a Tracker

A Tracker must first be created before one can be used to generate personalized URLs (PURLs) or QR codes in orders. To create a Tracker, make a POST request to the /trackers endpoint. An example in TypeScript is provided below.

async function createTracker() {
  const requestBody = { 
    redirectURLTemplate: "https://postgrid.com?name={{to.firstName}}",
    urlExpireAfterDays: 30
  };
  
  const requestOptions = {
   method: "POST",
   headers: {
     "Content-Type": "application/json",
     "x-api-key": "key_abcdefg", // Use your live/test api key here
   },
   body: JSON.stringify(requestBody),
  };
  
  const res = await fetch("https://api.postgrid.com/print-mail/v1/trackers", requestOptions);
  
  return await res.json();
}

This function will create a Tracker with a personalized URL containing a query parameter of the receiving contact's first name titled name. When supplying the redirectURLTemplate, any merge variable available in the order can be accessed. This includes the to and from contacts as well as any custom merge variables.

After a Tracker has been created, it can be referenced in an order to generate PURLs and QR codes. For more details on the request, refer to our API documentation.

Using Trackers in an order

In this example we will create a sample letter which will have a QR code created by a Tracker. An example in TypeScript is provided below.

function createOrderHTML(trackerID: string) {
  const html = `
<html>
  <!-- A short URL will be generated and displayed -->
  <p>Check out our cool URL: {{${trackerID}}}</p>

  <p>Scan the QR code to be taken to our website</p>
  <!-- A QR code will be generated instead of a short URL if `.qrcode` is supplied after the Tracker's ID -->
  <img src="{{${trackerID}.qrcode}}">
</html>
`;
  
  return html;
}

async function createLetter(trackerID: string) {
  const requestBody = {
    html: createOrderHTML(trackerID),
    to: "contact_abcd",
    from: "contact_efgh",
    size: "us_letter"
  };
  
  const requestOptions = {
		method: "POST",
    headers: {
    	"Content-Type": "application/json",
      "x-api-key": "key_abcdefg", // Use your live/test api key here
    },
    body: JSON.stringify(requestBody),
  };
  
  const letter = await fetch("https://api.postgrid.com/print-mail/v1/letters", requestOptions);
  
  return await letter.json();
}

In this example we create a letter with HTML that contains a merge variable of a Tracker we wish to use. Both a short URL and a QR code which lead to the Trackers redirectURLTemplate will be generated.

Check out our guide Sending Letters using the API for more information about creating letters using the API.

Tracking Tracker metrics

Visit counts

Interactions with Trackers are tracked using Tracker Visits. Although the overall number of interactions are recorded on the Tracker itself, Tracker Visits provide information by recording the device used, IP address and referred Tracker/order ID for each visit.

Since Trackers contain the unique and total number of visits, to obtain this information simply query for the desired Tracker. An example in TypeScript is provided below.

async function fetchTracker(trackerID: string) {
  const requestOptions = {
		method: "GET",
    headers: {
      "x-api-key": "key_abcdefg", // Use your live/test api key here
    }
  };
  
  const tracker = await fetch(`https://api.postgrid.com/print-mail/v1/trackers/${trackerID}`, requestOptions);
  
  return await tracker.json();
}

This will return the desired Tracker if it exists which will have information regarding the unique and total number of visits.

Check out the Trackers documentation for an exhaustive list of fields available.

Individual Visits

Tracker Visits provide more targeted information regarding the interactions on a Tracker and are useful when more information is needed on the individual visits of a Tracker. To view individual visits for a Tracker, query the /tracker/:id endpoint. An example in TypeScript is provided below.

async function fetchVisits(trackerID: string) {
  const requestOptions = {
		method: "GET",
    headers: {
      "x-api-key": "key_abcdefg", // Use your live/test api key here
    }
  };
  
  const visits = await fetch(`https://api.postgrid.com/print-mail/v1/trackers/${trackerID}/visits`, requestOptions);
  
  return await visits.json();
}

This will return a list of paginated Tracker Visits.

Check out the Tracker Visits documentation for an exhaustive list of fields available.

Updating Trackers

You may find yourself needing to modify the expiration date or base URL of the Trackers generated PURLs to better fit your requirements. In this case, you can modify an existing Tracker by making a POST request to the /trackers/:id endpoint. An example in TypeScript is provided below.

async function updateTracker(trackerID: string) {
  const requestBody = { 
    redirectURLTemplate: "https://postgrid.com?name={{to.firstName}}&id={{to.metadata.id}}",
    urlExpireAfterDays: 60
  };
  
  const requestOptions = {
   method: "POST",
   headers: {
     "Content-Type": "application/json",
     "x-api-key": "key_abcdefg", // Use your live/test api key here
   },
   body: JSON.stringify(requestBody),
  };
  
  const tracker = await fetch(`https://api.postgrid.com/print-mail/v1/trackers/${trackerID}`, requestOptions);
  
  return await tracker.json();
}

This will update the desired Tracker if it exists to have an updated redirect URL and URL expiration.

For more detailed information, refer to our API documentation.

Deleting Trackers

When a Tracker is no longer required, it can be deleted by making a DELETE request to the /trackers/:id endpoint. An example in TypeScript is provided below.

async function deleteTracker(trackerID: string) {
  const requestOptions = {
   method: "DELETE",
   headers: {
     "Content-Type": "application/json",
     "x-api-key": "key_abcdefg", // Use your live/test api key here
   },
  };
  
  const deleted = await fetch(`https://api.postgrid.com/print-mail/v1/trackers/${trackerID}`, requestOptions);
  
  return await deleted.json();
}

This will delete the requested Tracker if it exists meaning you will not be able to use it for future orders.

API Reference: https://postgrid.readme.io/reference/trackers