​

Open Tracking

​

📝 Endpoint

GET /api/v1/t/open

​

📋 Query Parameters

​

📤 Request Example

curl -X GET "https://api.posthoot.com/api/v1/t/open?token=tracking_token_123"

​

📥 Response

​

Success (200 OK)

{
  "id": "tracking_123",
  "emailId": "email_456",
  "campaignId": "campaign_789",
  "contactId": "contact_101",
  "event": "open",
  "timestamp": "2024-01-01T10:00:00Z",
  "ipAddress": "192.168.1.1",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36",
  "country": "US",
  "city": "New York",
  "region": "NY",
  "deviceType": "desktop",
  "browser": "Chrome",
  "os": "Windows",
  "metadata": {}
}

​

Error Responses

​

Invalid Token (401 Unauthorized)

{
  "error": "unauthorized",
  "message": "Invalid tracking token",
  "code": "INVALID_TOKEN"
}

​

Missing Token (400 Bad Request)

{
  "error": "validation_error",
  "message": "Token is required",
  "code": "MISSING_TOKEN"
}

​

🔍 How Open Tracking Works

​

1. Email Generation

<img src="https://api.posthoot.com/api/v1/t/open?token=abc123" 
     width="1" height="1" style="display:none;" alt="" />

​

2. Email Opening

• Email client loads the tracking pixel
• Browser makes a GET request to the tracking URL
• Posthoot records the open event

​

3. Data Collection

• IP Address: Recipient’s IP address
• User Agent: Browser and device information
• Geographic Data: Country, city, region
• Device Information: Device type, browser, OS
• Timestamp: Exact time of open

​

🛡️ Privacy Considerations

​

Data Minimization

• Only essential tracking data is collected
• IP addresses are anonymized after processing
• No personal information is stored in tracking tokens

​

Compliance

• GDPR compliant tracking
• Opt-out mechanisms available
• Clear privacy policy required

​

Security

• Tracking tokens are cryptographically secure
• Tokens expire after a reasonable time
• Rate limiting prevents abuse

​

📊 Tracking Data

​

Geographic Information

• Country: ISO country code (e.g., “US”, “CA”)
• City: City name (e.g., “New York”, “Toronto”)
• Region: State/province (e.g., “NY”, “ON”)

​

Device Information

• Device Type: “desktop”, “mobile”, “tablet”, “other”
• Browser: “Chrome”, “Safari”, “Firefox”, “Edge”
• OS: “Windows”, “macOS”, “iOS”, “Android”

​

Timing Information

• Timestamp: ISO 8601 format
• Timezone: Automatically detected from IP

​

🔧 Implementation Notes

​

Email Client Compatibility

• Gmail: Blocks tracking pixels by default
• Outlook: May block tracking pixels
• Apple Mail: Blocks tracking pixels in some cases
• Thunderbird: Generally allows tracking pixels

​

Fallback Tracking

• Link tracking (clicks)
• Engagement scoring based on other metrics
• Time-based analysis

​

Rate Limiting

• Tracking endpoints have rate limits
• Prevents abuse and spam
• Configurable per IP address

​

📈 Analytics Integration

​

Real-time Updates

• Campaign open rates
• Geographic breakdowns
• Device statistics
• Engagement scores

​

Webhook Notifications

{
  "event": "email.opened",
  "data": {
    "emailId": "email_123",
    "campaignId": "campaign_456",
    "recipient": "user@example.com",
    "timestamp": "2024-01-01T10:00:00Z",
    "location": {
      "country": "US",
      "city": "New York"
    },
    "device": {
      "type": "desktop",
      "browser": "Chrome"
    }
  }
}

​

🚨 Error Handling

​

Handle Blocked Tracking

// Check if tracking is blocked
function isTrackingBlocked(analytics) {
  return analytics.openCount === 0 && analytics.clickCount > 0;
}

// Use alternative metrics
function getEngagementScore(analytics) {
  if (isTrackingBlocked(analytics)) {
    // Use click rate and other metrics
    return analytics.clickRate * 2;
  }
  return analytics.engagementScore;
}

​

Graceful Degradation

// Handle missing tracking data
function processAnalytics(analytics) {
  if (!analytics.openCount && analytics.clickCount) {
    console.log('Open tracking may be blocked');
    // Use alternative engagement metrics
  }
  
  return {
    ...analytics,
    estimatedOpens: analytics.openCount || analytics.clickCount * 3
  };
}

​

📚 Related Endpoints

• Click Tracking - Handle email click tracking
• Email Analytics - Get email analytics
• Campaign Analytics - Get campaign analytics
• Webhooks - Set up real-time notifications