{
  "info": {
    "_postman_id": "mailsignal-api-v1",
    "name": "MailSignal API",
    "description": "Complete API collection for MailSignal email tracking service.\n\n## Authentication\nAll endpoints require an API key in the Authorization header:\n`Authorization: Bearer ms_live_xxxx`\n\nGet your API key from: https://mailsignal.eu/dashboard/settings\n\n## Base URL\nhttps://mailsignal.eu/api/v1",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{api_key}}",
        "type": "string"
      }
    ]
  },
  "variable": [
    {
      "key": "base_url",
      "value": "https://mailsignal.eu/api/v1",
      "type": "string"
    },
    {
      "key": "api_key",
      "value": "ms_live_your_api_key_here",
      "type": "string"
    },
    {
      "key": "track_id",
      "value": "",
      "type": "string"
    },
    {
      "key": "webhook_id",
      "value": "",
      "type": "string"
    }
  ],
  "item": [
    {
      "name": "Tracks",
      "description": "Create and manage email tracking pixels",
      "item": [
        {
          "name": "Create Track",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"recipient\": \"john@example.com\",\n  \"subject\": \"Meeting Tomorrow\",\n  \"campaign\": \"sales-outreach\"\n}"
            },
            "url": {
              "raw": "{{base_url}}/tracks",
              "host": ["{{base_url}}"],
              "path": ["tracks"]
            },
            "description": "Create a new tracking pixel for an email.\n\n### Request Body\n- `recipient` (required): Recipient email address\n- `subject` (optional): Email subject line\n- `campaign` (optional): Campaign identifier for grouping\n\n### Response\nReturns the created track with a `pixelUrl` to embed in your email."
          },
          "response": [
            {
              "name": "Success",
              "status": "Created",
              "code": 201,
              "body": "{\n  \"id\": \"trk_abc123xyz\",\n  \"recipient\": \"john@example.com\",\n  \"subject\": \"Meeting Tomorrow\",\n  \"campaign\": \"sales-outreach\",\n  \"pixelUrl\": \"https://mailsignal.eu/api/t/trk_abc123xyz\",\n  \"createdAt\": \"2025-01-28T07:00:00Z\",\n  \"opens\": []\n}"
            }
          ]
        },
        {
          "name": "List Tracks",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/tracks?limit=50",
              "host": ["{{base_url}}"],
              "path": ["tracks"],
              "query": [
                {
                  "key": "limit",
                  "value": "50",
                  "description": "Number of tracks to return (default: 50, max: 100)"
                },
                {
                  "key": "cursor",
                  "value": "",
                  "description": "Pagination cursor from previous response",
                  "disabled": true
                },
                {
                  "key": "campaign",
                  "value": "",
                  "description": "Filter by campaign name",
                  "disabled": true
                },
                {
                  "key": "opened",
                  "value": "",
                  "description": "Filter by open status (true/false)",
                  "disabled": true
                },
                {
                  "key": "from",
                  "value": "",
                  "description": "Filter tracks created after this date (ISO 8601)",
                  "disabled": true
                },
                {
                  "key": "to",
                  "value": "",
                  "description": "Filter tracks created before this date (ISO 8601)",
                  "disabled": true
                }
              ]
            },
            "description": "List all tracks with optional filtering and pagination."
          },
          "response": [
            {
              "name": "Success",
              "status": "OK",
              "code": 200,
              "body": "{\n  \"tracks\": [\n    {\n      \"id\": \"trk_abc123xyz\",\n      \"recipient\": \"john@example.com\",\n      \"subject\": \"Meeting Tomorrow\",\n      \"campaign\": \"sales-outreach\",\n      \"createdAt\": \"2025-01-28T07:00:00Z\",\n      \"openCount\": 3,\n      \"clickCount\": 1\n    }\n  ],\n  \"cursor\": \"eyJpZCI6InRya19hYmMxMjN4eXoifQ\",\n  \"hasMore\": true\n}"
            }
          ]
        },
        {
          "name": "Get Track",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/tracks/{{track_id}}",
              "host": ["{{base_url}}"],
              "path": ["tracks", "{{track_id}}"]
            },
            "description": "Get detailed information about a specific track including all opens."
          },
          "response": [
            {
              "name": "Success",
              "status": "OK",
              "code": 200,
              "body": "{\n  \"id\": \"trk_abc123xyz\",\n  \"recipient\": \"john@example.com\",\n  \"subject\": \"Meeting Tomorrow\",\n  \"campaign\": \"sales-outreach\",\n  \"createdAt\": \"2025-01-28T07:00:00Z\",\n  \"openCount\": 3,\n  \"clickCount\": 1,\n  \"opens\": [\n    {\n      \"timestamp\": \"2025-01-28T09:15:00Z\",\n      \"emailClient\": \"Gmail\",\n      \"device\": \"iPhone\",\n      \"location\": {\n        \"city\": \"Berlin\",\n        \"country\": \"Germany\"\n      }\n    }\n  ]\n}"
            }
          ]
        },
        {
          "name": "Delete Track",
          "request": {
            "method": "DELETE",
            "header": [],
            "url": {
              "raw": "{{base_url}}/tracks/{{track_id}}",
              "host": ["{{base_url}}"],
              "path": ["tracks", "{{track_id}}"]
            },
            "description": "Delete a specific track and all associated open/click data."
          },
          "response": [
            {
              "name": "Success",
              "status": "OK",
              "code": 200,
              "body": "{\n  \"success\": true,\n  \"message\": \"Track deleted successfully\"\n}"
            }
          ]
        }
      ]
    },
    {
      "name": "Analytics",
      "description": "Retrieve aggregated analytics data",
      "item": [
        {
          "name": "Get Analytics",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/analytics?period=30d",
              "host": ["{{base_url}}"],
              "path": ["analytics"],
              "query": [
                {
                  "key": "period",
                  "value": "30d",
                  "description": "Time period: 7d, 30d, 90d, 1y (default: 30d)"
                },
                {
                  "key": "campaign",
                  "value": "",
                  "description": "Filter by campaign",
                  "disabled": true
                },
                {
                  "key": "groupBy",
                  "value": "day",
                  "description": "Group results: day, week, month",
                  "disabled": true
                }
              ]
            },
            "description": "Get aggregated analytics for your email tracking."
          },
          "response": [
            {
              "name": "Success",
              "status": "OK",
              "code": 200,
              "body": "{\n  \"period\": \"30d\",\n  \"summary\": {\n    \"totalTracks\": 150,\n    \"totalOpens\": 89,\n    \"uniqueOpens\": 72,\n    \"openRate\": 48.0,\n    \"totalClicks\": 23,\n    \"clickRate\": 15.3\n  },\n  \"emailClients\": {\n    \"Gmail\": 45,\n    \"Outlook\": 28,\n    \"Apple Mail\": 16\n  },\n  \"devices\": {\n    \"Desktop\": 52,\n    \"Mobile\": 35,\n    \"Tablet\": 2\n  },\n  \"timeline\": [\n    { \"date\": \"2025-01-01\", \"opens\": 5, \"tracks\": 12 },\n    { \"date\": \"2025-01-02\", \"opens\": 8, \"tracks\": 15 }\n  ]\n}"
            }
          ]
        }
      ]
    },
    {
      "name": "Webhooks",
      "description": "Manage webhook endpoints for real-time notifications",
      "item": [
        {
          "name": "Create Webhook",
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"url\": \"https://yoursite.com/webhooks/mailsignal\",\n  \"events\": [\"track.opened\", \"link.clicked\"]\n}"
            },
            "url": {
              "raw": "{{base_url}}/webhooks",
              "host": ["{{base_url}}"],
              "path": ["webhooks"]
            },
            "description": "Create a new webhook endpoint.\n\n### Request Body\n- `url` (required): Your webhook endpoint URL (HTTPS required)\n- `events` (required): Array of events to subscribe to\n\n### Available Events\n- `track.created` - When a new track is created\n- `track.opened` - When an email is opened\n- `track.opened.first` - First open of an email (unique)\n- `link.clicked` - When a tracked link is clicked\n- `track.deleted` - When a track is deleted"
          },
          "response": [
            {
              "name": "Success",
              "status": "Created",
              "code": 201,
              "body": "{\n  \"id\": \"wh_abc123xyz\",\n  \"url\": \"https://yoursite.com/webhooks/mailsignal\",\n  \"events\": [\"track.opened\", \"link.clicked\"],\n  \"secret\": \"whsec_xxxxxxxxxxxxx\",\n  \"active\": true,\n  \"createdAt\": \"2025-01-28T07:00:00Z\"\n}"
            }
          ]
        },
        {
          "name": "List Webhooks",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/webhooks",
              "host": ["{{base_url}}"],
              "path": ["webhooks"]
            },
            "description": "List all configured webhooks."
          },
          "response": [
            {
              "name": "Success",
              "status": "OK",
              "code": 200,
              "body": "{\n  \"webhooks\": [\n    {\n      \"id\": \"wh_abc123xyz\",\n      \"url\": \"https://yoursite.com/webhooks/mailsignal\",\n      \"events\": [\"track.opened\", \"link.clicked\"],\n      \"active\": true,\n      \"createdAt\": \"2025-01-28T07:00:00Z\"\n    }\n  ]\n}"
            }
          ]
        },
        {
          "name": "Get Webhook",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/webhooks/{{webhook_id}}",
              "host": ["{{base_url}}"],
              "path": ["webhooks", "{{webhook_id}}"]
            },
            "description": "Get details about a specific webhook including recent deliveries."
          },
          "response": [
            {
              "name": "Success",
              "status": "OK",
              "code": 200,
              "body": "{\n  \"id\": \"wh_abc123xyz\",\n  \"url\": \"https://yoursite.com/webhooks/mailsignal\",\n  \"events\": [\"track.opened\", \"link.clicked\"],\n  \"active\": true,\n  \"createdAt\": \"2025-01-28T07:00:00Z\",\n  \"recentDeliveries\": [\n    {\n      \"id\": \"del_123\",\n      \"event\": \"track.opened\",\n      \"success\": true,\n      \"statusCode\": 200,\n      \"createdAt\": \"2025-01-28T09:00:00Z\"\n    }\n  ]\n}"
            }
          ]
        },
        {
          "name": "Update Webhook",
          "request": {
            "method": "PUT",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"url\": \"https://yoursite.com/webhooks/mailsignal-v2\",\n  \"events\": [\"track.opened\", \"track.opened.first\", \"link.clicked\"],\n  \"active\": true\n}"
            },
            "url": {
              "raw": "{{base_url}}/webhooks/{{webhook_id}}",
              "host": ["{{base_url}}"],
              "path": ["webhooks", "{{webhook_id}}"]
            },
            "description": "Update a webhook's configuration."
          },
          "response": [
            {
              "name": "Success",
              "status": "OK",
              "code": 200,
              "body": "{\n  \"id\": \"wh_abc123xyz\",\n  \"url\": \"https://yoursite.com/webhooks/mailsignal-v2\",\n  \"events\": [\"track.opened\", \"track.opened.first\", \"link.clicked\"],\n  \"active\": true,\n  \"createdAt\": \"2025-01-28T07:00:00Z\"\n}"
            }
          ]
        },
        {
          "name": "Delete Webhook",
          "request": {
            "method": "DELETE",
            "header": [],
            "url": {
              "raw": "{{base_url}}/webhooks/{{webhook_id}}",
              "host": ["{{base_url}}"],
              "path": ["webhooks", "{{webhook_id}}"]
            },
            "description": "Delete a webhook endpoint."
          },
          "response": [
            {
              "name": "Success",
              "status": "OK",
              "code": 200,
              "body": "{\n  \"success\": true,\n  \"message\": \"Webhook deleted successfully\"\n}"
            }
          ]
        },
        {
          "name": "Test Webhook",
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{base_url}}/webhooks/{{webhook_id}}/test",
              "host": ["{{base_url}}"],
              "path": ["webhooks", "{{webhook_id}}", "test"]
            },
            "description": "Send a test payload to the webhook endpoint to verify it's working correctly."
          },
          "response": [
            {
              "name": "Success",
              "status": "OK",
              "code": 200,
              "body": "{\n  \"success\": true,\n  \"statusCode\": 200,\n  \"responseTime\": 245\n}"
            }
          ]
        }
      ]
    },
    {
      "name": "API Keys",
      "description": "Manage API keys (for reference - typically done via dashboard)",
      "item": [
        {
          "name": "List API Keys",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{base_url}}/api-keys",
              "host": ["{{base_url}}"],
              "path": ["api-keys"]
            },
            "description": "List all API keys (secrets are not returned)."
          },
          "response": [
            {
              "name": "Success",
              "status": "OK",
              "code": 200,
              "body": "{\n  \"keys\": [\n    {\n      \"id\": \"key_abc123\",\n      \"name\": \"Production\",\n      \"keyPrefix\": \"ms_live_xxxx\",\n      \"permissions\": [\"read\", \"write\"],\n      \"lastUsedAt\": \"2025-01-28T09:00:00Z\",\n      \"createdAt\": \"2025-01-01T00:00:00Z\"\n    }\n  ]\n}"
            }
          ]
        }
      ]
    }
  ],
  "event": [
    {
      "listen": "prerequest",
      "script": {
        "type": "text/javascript",
        "exec": [
          "// Ensure API key is set",
          "if (!pm.variables.get('api_key') || pm.variables.get('api_key') === 'ms_live_your_api_key_here') {",
          "    console.warn('⚠️ Please set your API key in the collection variables');",
          "}"
        ]
      }
    },
    {
      "listen": "test",
      "script": {
        "type": "text/javascript",
        "exec": [
          "// Log rate limit info",
          "const rateLimit = pm.response.headers.get('X-RateLimit-Remaining');",
          "if (rateLimit) {",
          "    console.log('Rate limit remaining:', rateLimit);",
          "}"
        ]
      }
    }
  ]
}