# Trackers ## Create Tracker `print_mail.trackers.create(TrackerCreateParams**kwargs) -> TrackerCreateResponse` **post** `/print-mail/v1/trackers` Create a Tracker. ### Parameters - `redirect_url_template: str` The base template for URLs generated by this Tracker. - `url_expire_after_days: Literal[30, 60, 90, 2 more]` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### Returns - `class TrackerCreateResponse: …` - `id: str` A unique ID prefixed with tracker_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["tracker"]` Always `tracker`. - `"tracker"` - `redirect_url_template: str` The base template for URLs generated by this Tracker. - `unique_visit_count: int` The unique number of interactions the Tracker has had. - `updated_at: datetime` The UTC time at which this resource was last updated. - `url_expire_after_days: Literal[30, 60, 90, 2 more]` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `visit_count: int` The total number of interactions the Tracker has had. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### Example ```python import os from postgrid import PostGrid client = PostGrid( print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted ) tracker = client.print_mail.trackers.create( redirect_url_template="https://postgrid.com?name={{to.firstName}}", url_expire_after_days=30, ) print(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 `print_mail.trackers.list(TrackerListParams**kwargs) -> SyncSkipLimit[TrackerListResponse]` **get** `/print-mail/v1/trackers` Retrieve a paginated list of Trackers. ### Parameters - `limit: Optional[int]` - `search: Optional[str]` 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: Optional[int]` ### Returns - `class TrackerListResponse: …` - `id: str` A unique ID prefixed with tracker_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["tracker"]` Always `tracker`. - `"tracker"` - `redirect_url_template: str` The base template for URLs generated by this Tracker. - `unique_visit_count: int` The unique number of interactions the Tracker has had. - `updated_at: datetime` The UTC time at which this resource was last updated. - `url_expire_after_days: Literal[30, 60, 90, 2 more]` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `visit_count: int` The total number of interactions the Tracker has had. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### Example ```python import os from postgrid import PostGrid client = PostGrid( print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted ) page = client.print_mail.trackers.list() page = page.data[0] print(page.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 `print_mail.trackers.update(strid, TrackerUpdateParams**kwargs) -> TrackerUpdateResponse` **post** `/print-mail/v1/trackers/{id}` Update a Tracker by ID. ### Parameters - `id: str` - `redirect_url_template: str` The base template for URLs generated by this Tracker. - `url_expire_after_days: Literal[30, 60, 90, 2 more]` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### Returns - `class TrackerUpdateResponse: …` - `id: str` A unique ID prefixed with tracker_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["tracker"]` Always `tracker`. - `"tracker"` - `redirect_url_template: str` The base template for URLs generated by this Tracker. - `unique_visit_count: int` The unique number of interactions the Tracker has had. - `updated_at: datetime` The UTC time at which this resource was last updated. - `url_expire_after_days: Literal[30, 60, 90, 2 more]` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `visit_count: int` The total number of interactions the Tracker has had. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### Example ```python import os from postgrid import PostGrid client = PostGrid( print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted ) tracker = client.print_mail.trackers.update( id="id", redirect_url_template="https://postgrid.com?firstName={{to.firstName}}", url_expire_after_days=90, ) print(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 `print_mail.trackers.retrieve(strid) -> TrackerRetrieveResponse` **get** `/print-mail/v1/trackers/{id}` Retrieve a Tracker by ID. ### Parameters - `id: str` ### Returns - `class TrackerRetrieveResponse: …` - `id: str` A unique ID prefixed with tracker_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["tracker"]` Always `tracker`. - `"tracker"` - `redirect_url_template: str` The base template for URLs generated by this Tracker. - `unique_visit_count: int` The unique number of interactions the Tracker has had. - `updated_at: datetime` The UTC time at which this resource was last updated. - `url_expire_after_days: Literal[30, 60, 90, 2 more]` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `visit_count: int` The total number of interactions the Tracker has had. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### Example ```python import os from postgrid import PostGrid client = PostGrid( print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted ) tracker = client.print_mail.trackers.retrieve( "id", ) print(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 `print_mail.trackers.delete(strid) -> TrackerDeleteResponse` **delete** `/print-mail/v1/trackers/{id}` Delete a Tracker by ID. Note that this operation cannot be undone. ### Parameters - `id: str` ### Returns - `class TrackerDeleteResponse: …` - `id: str` A unique ID prefixed with tracker_ - `deleted: Literal[true]` - `true` - `object: Literal["tracker"]` Always `tracker`. - `"tracker"` ### Example ```python import os from postgrid import PostGrid client = PostGrid( print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted ) tracker = client.print_mail.trackers.delete( "id", ) print(tracker.id) ``` #### Response ```json { "id": "tracker_123456789abcdefghijklmnopqrstuvwxyz", "object": "tracker", "deleted": true } ``` ## List Tracker Visits `print_mail.trackers.retrieve_visits(strid, TrackerRetrieveVisitsParams**kwargs) -> SyncSkipLimit[TrackerRetrieveVisitsResponse]` **get** `/print-mail/v1/trackers/{id}/visits` Retrieve a paginated list of visits for a Tracker. ### Parameters - `id: str` - `limit: Optional[int]` - `search: Optional[str]` 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: Optional[int]` ### Returns - `class TrackerRetrieveVisitsResponse: …` - `id: str` A unique ID prefixed with `tracker_visit_`. - `created_at: datetime` The UTC time at which this visit was created. - `device: str` The type of device associated with the visit. - `ip_address: str` The IP address associated with the visit. - `live: bool` Indicates if the visit was used in a live order or not. - `object: Literal["tracker_visit"]` Always `tracker_visit`. - `"tracker_visit"` - `order_id: str` The ID of the order where the interaction occurred. - `tracker: str` The ID of the tracker related to this visit. - `updated_at: datetime` The UTC time at which this visit was last updated. ### Example ```python import os from postgrid import PostGrid client = PostGrid( print_mail_api_key=os.environ.get("POSTGRID_PRINT_MAIL_API_KEY"), # This is the default and can be omitted ) page = client.print_mail.trackers.retrieve_visits( id="id", ) page = page.data[0] print(page.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 - `class TrackerCreateResponse: …` - `id: str` A unique ID prefixed with tracker_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["tracker"]` Always `tracker`. - `"tracker"` - `redirect_url_template: str` The base template for URLs generated by this Tracker. - `unique_visit_count: int` The unique number of interactions the Tracker has had. - `updated_at: datetime` The UTC time at which this resource was last updated. - `url_expire_after_days: Literal[30, 60, 90, 2 more]` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `visit_count: int` The total number of interactions the Tracker has had. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### Tracker List Response - `class TrackerListResponse: …` - `id: str` A unique ID prefixed with tracker_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["tracker"]` Always `tracker`. - `"tracker"` - `redirect_url_template: str` The base template for URLs generated by this Tracker. - `unique_visit_count: int` The unique number of interactions the Tracker has had. - `updated_at: datetime` The UTC time at which this resource was last updated. - `url_expire_after_days: Literal[30, 60, 90, 2 more]` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `visit_count: int` The total number of interactions the Tracker has had. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### Tracker Update Response - `class TrackerUpdateResponse: …` - `id: str` A unique ID prefixed with tracker_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["tracker"]` Always `tracker`. - `"tracker"` - `redirect_url_template: str` The base template for URLs generated by this Tracker. - `unique_visit_count: int` The unique number of interactions the Tracker has had. - `updated_at: datetime` The UTC time at which this resource was last updated. - `url_expire_after_days: Literal[30, 60, 90, 2 more]` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `visit_count: int` The total number of interactions the Tracker has had. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### Tracker Retrieve Response - `class TrackerRetrieveResponse: …` - `id: str` A unique ID prefixed with tracker_ - `created_at: datetime` The UTC time at which this resource was created. - `live: bool` `true` if this is a live mode resource else `false`. - `object: Literal["tracker"]` Always `tracker`. - `"tracker"` - `redirect_url_template: str` The base template for URLs generated by this Tracker. - `unique_visit_count: int` The unique number of interactions the Tracker has had. - `updated_at: datetime` The UTC time at which this resource was last updated. - `url_expire_after_days: Literal[30, 60, 90, 2 more]` The number of days generated Tracker URLs remain valid. - `30` - `60` - `90` - `180` - `365` - `visit_count: int` The total number of interactions the Tracker has had. - `description: Optional[str]` An optional string describing this resource. Will be visible in the API and the dashboard. - `metadata: Optional[Dict[str, object]]` See the section on Metadata. ### Tracker Delete Response - `class TrackerDeleteResponse: …` - `id: str` A unique ID prefixed with tracker_ - `deleted: Literal[true]` - `true` - `object: Literal["tracker"]` Always `tracker`. - `"tracker"` ### Tracker Retrieve Visits Response - `class TrackerRetrieveVisitsResponse: …` - `id: str` A unique ID prefixed with `tracker_visit_`. - `created_at: datetime` The UTC time at which this visit was created. - `device: str` The type of device associated with the visit. - `ip_address: str` The IP address associated with the visit. - `live: bool` Indicates if the visit was used in a live order or not. - `object: Literal["tracker_visit"]` Always `tracker_visit`. - `"tracker_visit"` - `order_id: str` The ID of the order where the interaction occurred. - `tracker: str` The ID of the tracker related to this visit. - `updated_at: datetime` The UTC time at which this visit was last updated.