API Documentation

Complete reference for integrating with Mail Tracker API

Back to Dashboard

📚 Overview

The Mail Tracker API allows you to create tracking pixels, generate unique tracking URLs for email recipients, and monitor email opens with detailed analytics.

Base URL:
https://mailtrack.thanghm.tech
Rate Limiting:
Generate tokens endpoint is limited to 10 requests per 15 minutes with a maximum of 10,000 emails per request.

🔐 Authentication

Currently, this API does not require authentication. All endpoints are publicly accessible. For production use, consider implementing API key authentication.

🚀 API Endpoints

Create Tracking Pixel

Create a new tracking pixel programmatically. You can optionally upload a custom image to be displayed when the email is opened.

POST multipart/form-data
https://mailtrack.thanghm.tech/api/v1/pixels
Request Parameters
Parameter Type Description
namerequired string Name/title for your tracking pixel campaign
imageoptional file Custom image file (max 5MB). Supported formats: JPG, PNG, GIF, WebP
Example Request
cURL
# With custom image
curl -X POST \
  -F "name=My Campaign Pixel" \
  -F "image=@/path/to/image.png" \
  https://mailtrack.thanghm.tech/api/v1/pixels

# Without image (JSON)
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"name": "My Campaign Pixel"}' \
  https://mailtrack.thanghm.tech/api/v1/pixels
Response
201 Created
{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "name": "My Campaign Pixel",
  "createdAt": "2025-11-06T12:00:00.000Z",
  "imagePath": "/uploads/your-uploaded-image.png",
  "trackingUrl": "https://mailtrack.thanghm.tech/tracker/a1b2c3d4.png",
  "logsUrl": "https://mailtrack.thanghm.tech/logs/a1b2c3d4"
}
400 Bad Request
{ "error": "Pixel name is required." }

Track Pixel Open

This endpoint tracks when an email is opened. It returns a 1x1 transparent PNG image (or your custom image). Include this URL as an image in your HTML emails.

GET image/png
https://mailtrack.thanghm.tech/tracker/{pixelId}.png?token={token}
URL Parameters
Parameter Description
pixelIdrequired UUID of the tracking pixel
tokenoptional Unique token to identify the recipient (generated via bulk token API)
Example Usage
HTML Email
<img src="https://mailtrack.thanghm.tech/tracker/a1b2c3d4.png?token=tok_abc123" 
     width="1" height="1" style="display:none;" />
Response: Returns PNG image and logs the open event with IP, user agent, location, and timestamp.

Generate Tracking URLs (Bulk)

Bulk generate unique tracking URLs for email recipients. Each recipient gets a unique token for individual tracking. Maximum 10,000 emails per request.

POST application/json Rate Limited
https://mailtrack.thanghm.tech/api/v1/pixels/{pixelId}/generate-tokens
Rate Limit: 10 requests per 15 minutes, max 10,000 emails per request
Request Body
JSON
{
  "emails": [
    "user1@example.com",
    "user2@example.com",
    "user3@example.com"
  ]
}
Example Request
cURL
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"emails": ["user1@example.com", "user2@example.com"]}' \
  https://mailtrack.thanghm.tech/api/v1/pixels/a1b2c3d4/generate-tokens
Response
200 OK
{
  "success": true,
  "pixelId": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "generated": 2,
  "tokens": [
    {
      "email": "user1@example.com",
      "token": "tok_abc123xyz",
      "trackingUrl": "https://mailtrack.thanghm.tech/tracker/a1b2c3d4.png?token=tok_abc123xyz"
    },
    {
      "email": "user2@example.com",
      "token": "tok_def456uvw",
      "trackingUrl": "https://mailtrack.thanghm.tech/tracker/a1b2c3d4.png?token=tok_def456uvw"
    }
  ]
}
Possible Errors:
400 - Emails array is required / Invalid email format / Max 10,000 emails allowed
404 - Pixel not found
429 - Too many requests. Maximum 10 requests per 15 minutes

Export Recipients to CSV

Export all recipients and their tracking URLs to a CSV file. Supports large datasets with streaming for efficient memory usage.

GET text/csv
https://mailtrack.thanghm.tech/api/v1/pixels/{pixelId}/generate-tokens/csv
CSV Columns
Column Description
Email Recipient email address
Token Unique tracking token
Tracking URL Full tracking URL to embed in email
Created At Token generation timestamp
Example Request
cURL
curl -X GET \
  https://mailtrack.thanghm.tech/api/v1/pixels/a1b2c3d4/generate-tokens/csv \
  -o recipients.csv
Response: Downloads CSV file named recipients-{pixelId}.csv
404 Not Found
{ "error": "Pixel not found" }

View Pixel Logs

View detailed logs for a specific tracking pixel with pagination. This is a web interface, not a JSON API.

GET text/html
https://mailtrack.thanghm.tech/logs/{pixelId}?page={pageNumber}
Query Parameters
Parameter Description
pageoptional Page number for pagination (50 logs per page, default: 1)
Response: HTML page displaying logs with IP address, location, device info, user agent, and timestamps

Delete Single Recipient

Delete a specific recipient and their tracking token. Tracking logs for this recipient will be preserved for analytics purposes.

DELETE application/json
https://mailtrack.thanghm.tech/api/v1/recipients/{recipientId}
URL Parameters
Parameter Description
recipientIdrequired Unique ID of the recipient to delete
Example Request
cURL
curl -X DELETE \
  -H "Content-Type: application/json" \
  https://mailtrack.thanghm.tech/api/v1/recipients/507f1f77bcf86cd799439011
Response
200 OK
{
  "success": true,
  "message": "Recipient deleted successfully",
  "deletedEmail": "user@example.com"
}
Note: Only the recipient token is deleted. Historical tracking logs remain for analytics.
404 Not Found
{ "error": "Recipient not found" }

Delete Tracking Pixel

Delete a tracking pixel and all associated data including logs, tokens, and uploaded images. This is a web form submission.

POST application/x-www-form-urlencoded
https://mailtrack.thanghm.tech/delete/{pixelId}
Warning: This action is irreversible. All tracking data will be permanently deleted.
Response: Redirects to dashboard after successful deletion

⚠️ Error Responses

The API uses standard HTTP status codes to indicate success or failure.

Status Code Meaning Description
200 OK Request succeeded
201 Created Resource successfully created
400 Bad Request Invalid request parameters or body
404 Not Found Requested resource does not exist
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server encountered an error
Error Response Format
JSON
{
  "error": "Error message describing what went wrong"
}