# Trackers ## Create Tracker `client.printMail.trackers.create(TrackerCreateParamsbody, RequestOptionsoptions?): TrackerCreateResponse` **post** `/print-mail/v1/trackers` Create a Tracker. ### Parameters - `body: TrackerCreateParams` - `redirectURLTemplate: string` The base template for URLs generated by this Tracker. - `urlExpireAfterDays: 30 | 60 | 90 | 2 more` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `description?: string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata?: Record` See the section on Metadata. ### Returns - `TrackerCreateResponse` - `id: string` A unique ID prefixed with tracker_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "tracker"` Always `tracker`. - `"tracker"` - `redirectURLTemplate: string` The base template for URLs generated by this Tracker. - `uniqueVisitCount: number` The unique number of interactions the Tracker has had. - `updatedAt: string` The UTC time at which this resource was last updated. - `urlExpireAfterDays: 30 | 60 | 90 | 2 more` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `visitCount: number` The total number of interactions the Tracker has had. - `description?: string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata?: Record` See the section on Metadata. ### Example ```typescript import PostGrid from 'postgrid-node'; const client = new PostGrid({ printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted }); const tracker = await client.printMail.trackers.create({ redirectURLTemplate: 'https://postgrid.com?name={{to.firstName}}', urlExpireAfterDays: 30, }); console.log(tracker.id); ``` #### Response ```json { "id": "tracker_123456789abcdefghijklmnopqrstuvwxyz", "object": "tracker", "live": false, "redirectURLTemplate": "https://postgrid.com?name={{to.firstName}}", "urlExpireAfterDays": 30, "visitCount": 0, "uniqueVisitCount": 0, "createdAt": "2020-11-12T23:30:12.581Z", "updatedAt": "2020-11-12T23:30:12.581Z" } ``` ## List Trackers `client.printMail.trackers.list(TrackerListParamsquery?, RequestOptionsoptions?): SkipLimit` **get** `/print-mail/v1/trackers` Retrieve a paginated list of Trackers. ### Parameters - `query: TrackerListParams` - `limit?: number` - `search?: string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip?: number` ### Returns - `TrackerListResponse` - `id: string` A unique ID prefixed with tracker_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "tracker"` Always `tracker`. - `"tracker"` - `redirectURLTemplate: string` The base template for URLs generated by this Tracker. - `uniqueVisitCount: number` The unique number of interactions the Tracker has had. - `updatedAt: string` The UTC time at which this resource was last updated. - `urlExpireAfterDays: 30 | 60 | 90 | 2 more` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `visitCount: number` The total number of interactions the Tracker has had. - `description?: string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata?: Record` See the section on Metadata. ### Example ```typescript import PostGrid from 'postgrid-node'; const client = new PostGrid({ printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const trackerListResponse of client.printMail.trackers.list()) { console.log(trackerListResponse.id); } ``` #### Response ```json { "object": "list", "limit": 10, "skip": 0, "totalCount": 1, "data": [ { "id": "tracker_123456789abcdefghijklmnopqrstuvwxyz", "object": "tracker", "live": false, "redirectURLTemplate": "https://postgrid.com?firstName={{to.firstName}}", "urlExpireAfterDays": 90, "visitCount": 0, "uniqueVisitCount": 0, "createdAt": "2020-11-12T23:30:12.581Z", "updatedAt": "2020-11-12T23:31:12.581Z" } ] } ``` ## Update Tracker `client.printMail.trackers.update(stringid, TrackerUpdateParamsbody, RequestOptionsoptions?): TrackerUpdateResponse` **post** `/print-mail/v1/trackers/{id}` Update a Tracker by ID. ### Parameters - `id: string` - `body: TrackerUpdateParams` - `redirectURLTemplate: string` The base template for URLs generated by this Tracker. - `urlExpireAfterDays: 30 | 60 | 90 | 2 more` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `description?: string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata?: Record` See the section on Metadata. ### Returns - `TrackerUpdateResponse` - `id: string` A unique ID prefixed with tracker_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "tracker"` Always `tracker`. - `"tracker"` - `redirectURLTemplate: string` The base template for URLs generated by this Tracker. - `uniqueVisitCount: number` The unique number of interactions the Tracker has had. - `updatedAt: string` The UTC time at which this resource was last updated. - `urlExpireAfterDays: 30 | 60 | 90 | 2 more` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `visitCount: number` The total number of interactions the Tracker has had. - `description?: string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata?: Record` See the section on Metadata. ### Example ```typescript import PostGrid from 'postgrid-node'; const client = new PostGrid({ printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted }); const tracker = await client.printMail.trackers.update('id', { redirectURLTemplate: 'https://postgrid.com?firstName={{to.firstName}}', urlExpireAfterDays: 90, }); console.log(tracker.id); ``` #### Response ```json { "id": "tracker_123456789abcdefghijklmnopqrstuvwxyz", "object": "tracker", "live": false, "redirectURLTemplate": "https://postgrid.com?firstName={{to.firstName}}", "urlExpireAfterDays": 90, "visitCount": 0, "uniqueVisitCount": 0, "createdAt": "2020-11-12T23:30:12.581Z", "updatedAt": "2020-11-12T23:31:12.581Z" } ``` ## Get Tracker `client.printMail.trackers.retrieve(stringid, RequestOptionsoptions?): TrackerRetrieveResponse` **get** `/print-mail/v1/trackers/{id}` Retrieve a Tracker by ID. ### Parameters - `id: string` ### Returns - `TrackerRetrieveResponse` - `id: string` A unique ID prefixed with tracker_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "tracker"` Always `tracker`. - `"tracker"` - `redirectURLTemplate: string` The base template for URLs generated by this Tracker. - `uniqueVisitCount: number` The unique number of interactions the Tracker has had. - `updatedAt: string` The UTC time at which this resource was last updated. - `urlExpireAfterDays: 30 | 60 | 90 | 2 more` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `visitCount: number` The total number of interactions the Tracker has had. - `description?: string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata?: Record` See the section on Metadata. ### Example ```typescript import PostGrid from 'postgrid-node'; const client = new PostGrid({ printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted }); const tracker = await client.printMail.trackers.retrieve('id'); console.log(tracker.id); ``` #### Response ```json { "id": "tracker_123456789abcdefghijklmnopqrstuvwxyz", "object": "tracker", "live": false, "redirectURLTemplate": "https://postgrid.com?firstName={{to.firstName}}", "urlExpireAfterDays": 90, "visitCount": 0, "uniqueVisitCount": 0, "createdAt": "2020-11-12T23:30:12.581Z", "updatedAt": "2020-11-12T23:31:12.581Z" } ``` ## Delete Tracker `client.printMail.trackers.delete(stringid, RequestOptionsoptions?): TrackerDeleteResponse` **delete** `/print-mail/v1/trackers/{id}` Delete a Tracker by ID. Note that this operation cannot be undone. ### Parameters - `id: string` ### Returns - `TrackerDeleteResponse` - `id: string` A unique ID prefixed with tracker_ - `deleted: true` - `true` - `object: "tracker"` Always `tracker`. - `"tracker"` ### Example ```typescript import PostGrid from 'postgrid-node'; const client = new PostGrid({ printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted }); const tracker = await client.printMail.trackers.delete('id'); console.log(tracker.id); ``` #### Response ```json { "id": "tracker_123456789abcdefghijklmnopqrstuvwxyz", "object": "tracker", "deleted": true } ``` ## List Tracker Visits `client.printMail.trackers.retrieveVisits(stringid, TrackerRetrieveVisitsParamsquery?, RequestOptionsoptions?): SkipLimit` **get** `/print-mail/v1/trackers/{id}/visits` Retrieve a paginated list of visits for a Tracker. ### Parameters - `id: string` - `query: TrackerRetrieveVisitsParams` - `limit?: number` - `search?: string` You can supply any string to help narrow down the list of resources. For example, if you pass `"New York"` (quoted), it will return resources that have that string present somewhere in their response. Alternatively, you can supply a structured search query. See the documentation on `StructuredSearchQuery` for more details. - `skip?: number` ### Returns - `TrackerRetrieveVisitsResponse` - `id: string` A unique ID prefixed with `tracker_visit_`. - `createdAt: string` The UTC time at which this visit was created. - `device: string` The type of device associated with the visit. - `ipAddress: string` The IP address associated with the visit. - `live: boolean` Indicates if the visit was used in a live order or not. - `object: "tracker_visit"` Always `tracker_visit`. - `"tracker_visit"` - `orderID: string` The ID of the order where the interaction occurred. - `tracker: string` The ID of the tracker related to this visit. - `updatedAt: string` The UTC time at which this visit was last updated. ### Example ```typescript import PostGrid from 'postgrid-node'; const client = new PostGrid({ printMailAPIKey: process.env['POSTGRID_PRINT_MAIL_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const trackerRetrieveVisitsResponse of client.printMail.trackers.retrieveVisits('id')) { console.log(trackerRetrieveVisitsResponse.id); } ``` #### Response ```json { "object": "list", "limit": 10, "skip": 0, "totalCount": 1, "data": [ { "id": "tracker_visit_123456789abcdefghijklmnopqrstuvwxyz", "object": "tracker_visit", "live": false, "tracker": "tracker_123456789abcdefghijklmnopqrstuvwxyz", "orderID": "order_123456789abcdefghijklmnopqrstuvwxyz", "device": "Device Unknown", "ipAddress": "Unknown IP Address", "createdAt": "2020-11-12T23:30:12.581Z", "updatedAt": "2020-11-12T23:31:12.581Z" } ] } ``` ## Domain Types ### Tracker Create Response - `TrackerCreateResponse` - `id: string` A unique ID prefixed with tracker_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "tracker"` Always `tracker`. - `"tracker"` - `redirectURLTemplate: string` The base template for URLs generated by this Tracker. - `uniqueVisitCount: number` The unique number of interactions the Tracker has had. - `updatedAt: string` The UTC time at which this resource was last updated. - `urlExpireAfterDays: 30 | 60 | 90 | 2 more` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `visitCount: number` The total number of interactions the Tracker has had. - `description?: string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata?: Record` See the section on Metadata. ### Tracker List Response - `TrackerListResponse` - `id: string` A unique ID prefixed with tracker_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "tracker"` Always `tracker`. - `"tracker"` - `redirectURLTemplate: string` The base template for URLs generated by this Tracker. - `uniqueVisitCount: number` The unique number of interactions the Tracker has had. - `updatedAt: string` The UTC time at which this resource was last updated. - `urlExpireAfterDays: 30 | 60 | 90 | 2 more` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `visitCount: number` The total number of interactions the Tracker has had. - `description?: string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata?: Record` See the section on Metadata. ### Tracker Update Response - `TrackerUpdateResponse` - `id: string` A unique ID prefixed with tracker_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "tracker"` Always `tracker`. - `"tracker"` - `redirectURLTemplate: string` The base template for URLs generated by this Tracker. - `uniqueVisitCount: number` The unique number of interactions the Tracker has had. - `updatedAt: string` The UTC time at which this resource was last updated. - `urlExpireAfterDays: 30 | 60 | 90 | 2 more` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `visitCount: number` The total number of interactions the Tracker has had. - `description?: string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata?: Record` See the section on Metadata. ### Tracker Retrieve Response - `TrackerRetrieveResponse` - `id: string` A unique ID prefixed with tracker_ - `createdAt: string` The UTC time at which this resource was created. - `live: boolean` `true` if this is a live mode resource else `false`. - `object: "tracker"` Always `tracker`. - `"tracker"` - `redirectURLTemplate: string` The base template for URLs generated by this Tracker. - `uniqueVisitCount: number` The unique number of interactions the Tracker has had. - `updatedAt: string` The UTC time at which this resource was last updated. - `urlExpireAfterDays: 30 | 60 | 90 | 2 more` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `visitCount: number` The total number of interactions the Tracker has had. - `description?: string` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata?: Record` See the section on Metadata. ### Tracker Delete Response - `TrackerDeleteResponse` - `id: string` A unique ID prefixed with tracker_ - `deleted: true` - `true` - `object: "tracker"` Always `tracker`. - `"tracker"` ### Tracker Retrieve Visits Response - `TrackerRetrieveVisitsResponse` - `id: string` A unique ID prefixed with `tracker_visit_`. - `createdAt: string` The UTC time at which this visit was created. - `device: string` The type of device associated with the visit. - `ipAddress: string` The IP address associated with the visit. - `live: boolean` Indicates if the visit was used in a live order or not. - `object: "tracker_visit"` Always `tracker_visit`. - `"tracker_visit"` - `orderID: string` The ID of the order where the interaction occurred. - `tracker: string` The ID of the tracker related to this visit. - `updatedAt: string` The UTC time at which this visit was last updated.