Message Tracking

4 endpoints

On-premise message analytics including opens, replies, and custom events

GET /messages/tracking/{id}

Get tracking status for a message

Retrieve the latest tracking metrics and recent events for a tracked message created via the send API. Includes aggregated open, click, and reply counts.

Parameters

id string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

Returns

Aggregated tracking details for a sent message including counters and most recent events.

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X GET "http://localhost:8080/messages/tracking/{id}"
                  
              

Example response 200

              {
  "tracking": {
    "id": "trk_01HZY8B4S9PD2TS2VYB2XWFR7P",
    "messageId": "msg_01HZY8AW50MP89C11DW00SHM3R"
  },
  "metrics": {
    "totalEvents": 6,
    "openCount": 3,
    "clickCount": 2,
    "replyCount": 1,
    "lastEventAt": "2024-06-12T19:00:00.000Z",
    "lastOpenedAt": "2024-06-12T18:45:10.000Z",
    "lastClickedAt": "2024-06-12T18:55:32.000Z",
    "lastRepliedAt": "2024-06-12T18:59:03.000Z"
  }
}
            

---

POST /messages/tracking/{id}/events

Record a tracking event by ID

Manually record tracking events (reply detected, custom status updates, etc.) using the tracked message identifier. Useful for server-side integrations.

Parameters

id string

In path • Required

Unique account identifier assigned by Riposte. You may also provide the custom user ID set during authentication; the API resolves it to the canonical account.

Request body

Required • application/json

Payload posted by tracking webhooks or manual instrumentation to record engagement.

Request body (application/json)

post-/messages/tracking/{id}/events-request-body-application/json

object<{ eventType, occurredAt, metadata, … }>

Payload posted by tracking webhooks or manual instrumentation to record engagement.

Field	Type	Description	Values
customEventName Optional	string	Required when eventType is custom min length 1	Example printed
eventType Required	string	Type of tracking event that occurred. openedclickedrepliedforwardedbounceddeliveredcustom	Example opened
ipAddress Optional	string	IP address associated with the event.	Example 203.0.113.24
metadata Optional	object	Optional metadata describing the event context.	Example { "linkId": "lnk_123", "location": "pricing-cta" }
occurredAt Optional	string (date-time)	Timestamp when the event happened.	Example 2024-06-12T18:45:10.000Z
source Optional	string	Source system that recorded the event.	Example pixel
userAgent Optional	string	User agent string reported by the client.	Example Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36

Returns

Wrapper object returned after a tracking event is recorded.

Content type: application/json

Status: 201

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X POST "http://localhost:8080/messages/tracking/{id}/events" \
                  
                    2
                      -H "Content-Type: application/json" \
                  
                    3
                      --data @- <<'BODY'
                  
                    4
                    {
                  
                    5
                      "eventType": "opened",
                  
                    6
                      "occurredAt": "2024-06-12T18:45:10.000Z",
                  
                    7
                      "source": "pixel",
                  
                    8
                      "ipAddress": "203.0.113.24",
                  
                    9
                      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
                  
                    10
                    }
                  
                    11
                    BODY
                  
              

Example response 201

              {
  "event": {
    "id": "trk_evt_01HZY8B0Y4J4ZHWJQJ9P9N3S8M",
    "eventType": "opened",
    "occurredAt": "2024-06-12T18:45:10.000Z"
  }
}
            

---

POST /messages/tracking/token/{token}/events

Record a tracking event by token

Record tracking activity when only the tracking token is available (e.g., via webhook headers).

Parameters

token string

In path • Required

Tracking token issued when the session was created

Request body

Required • application/json

Payload posted by tracking webhooks or manual instrumentation to record engagement.

Request body (application/json)

post-/messages/tracking/token/{token}/events-request-body-application/json

object<{ eventType, occurredAt, metadata, … }>

Payload posted by tracking webhooks or manual instrumentation to record engagement.

Field	Type	Description	Values
customEventName Optional	string	Required when eventType is custom min length 1	Example printed
eventType Required	string	Type of tracking event that occurred. openedclickedrepliedforwardedbounceddeliveredcustom	Example opened
ipAddress Optional	string	IP address associated with the event.	Example 203.0.113.24
metadata Optional	object	Optional metadata describing the event context.	Example { "linkId": "lnk_123", "location": "pricing-cta" }
occurredAt Optional	string (date-time)	Timestamp when the event happened.	Example 2024-06-12T18:45:10.000Z
source Optional	string	Source system that recorded the event.	Example pixel
userAgent Optional	string	User agent string reported by the client.	Example Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36

Returns

Wrapper object returned after a tracking event is recorded.

Content type: application/json

Status: 201

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X POST "http://localhost:8080/messages/tracking/token/{token}/events" \
                  
                    2
                      -H "Content-Type: application/json" \
                  
                    3
                      --data @- <<'BODY'
                  
                    4
                    {
                  
                    5
                      "eventType": "opened",
                  
                    6
                      "occurredAt": "2024-06-12T18:45:10.000Z",
                  
                    7
                      "source": "pixel",
                  
                    8
                      "ipAddress": "203.0.113.24",
                  
                    9
                      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
                  
                    10
                    }
                  
                    11
                    BODY
                  
              

Example response 201

              {
  "event": {
    "id": "trk_evt_01HZY8B0Y4J4ZHWJQJ9P9N3S8M",
    "eventType": "opened",
    "occurredAt": "2024-06-12T18:45:10.000Z"
  }
}
            

---

GET /tracking/pixel/{token}.gif

Transparent tracking pixel

1x1 transparent GIF used for open tracking. This endpoint is public and does not require authentication.

Parameters

token string

In path • Required

Tracking token issued when the session was created

Returns

Transparent pixel GIF

Content type: application/json

Status: 200

Example request Copy Copied! Copy failed

cURL

                
                    1
                    curl -X GET "http://localhost:8080/tracking/pixel/{token}.gif"
                  
              

Example response 200

No example response available.