Analytics

Analytics endpoints expose send metrics, engagement rates, and deliverability data at both account and per-campaign level. You can also track custom conversion events to measure downstream impact.

Auth scopes: analytics (read metrics) | send (write tracking events)

Plan gates on analytics features:

Basic metrics (opens, clicks, bounces): all plans
90-day history: Pro+
365-day history + heatmaps: Max+
Revenue analytics (/track/purchase, /analytics/revenue): Max+
Ecommerce tracking: Max+ (ecommerce_tracking feature flag)
Scheduled / exported reports: Max+

Endpoints

| Method | Path | Description | |--------|------|-------------| | GET | /api/v1/analytics/overview | Account-level dashboard metrics | | GET | /api/v1/analytics/campaigns/:id | Per-campaign metrics | | POST | /api/v1/track/event | Track a custom event | | POST | /api/v1/track/purchase | Track a purchase event |

GET /api/v1/analytics/overview

Returns aggregate metrics for all sends in the given time period.

curl "https://api.misar.io/mail/v1/analytics/overview?period=30d" \
  -H "Authorization: Bearer msk_YOUR_API_KEY"

Query Parameters

| Param | Type | Default | Notes | |-------|------|---------|-------| | period | string | 30d | Preset period: 7d, 30d, 90d | | from | string | — | ISO 8601 start date (overrides period) | | to | string | — | ISO 8601 end date (overrides period) |

Response

{
  "success": true,
  "period": {
    "from": "2026-03-07T00:00:00Z",
    "to":   "2026-04-06T23:59:59Z"
  },
  "metrics": {
    "sends":         12480,
    "delivered":     12210,
    "opens":         4884,
    "unique_opens":  3663,
    "clicks":        1221,
    "unique_clicks": 855,
    "bounces":       270,
    "hard_bounces":  48,
    "soft_bounces":  222,
    "complaints":    12,
    "unsubscribes":  36,
    "open_rate":     0.392,
    "click_rate":    0.098,
    "bounce_rate":   0.022,
    "complaint_rate":0.001
  }
}

GET /api/v1/analytics/campaigns/:id

Returns detailed metrics for a specific campaign.

curl "https://api.misar.io/mail/v1/analytics/campaigns/camp_abc123" \
  -H "Authorization: Bearer msk_YOUR_API_KEY"

Response

{
  "success": true,
  "campaign": {
    "id":     "camp_abc123",
    "name":   "April Newsletter",
    "status": "sent",
    "sent_at":"2026-04-01T09:00:00Z"
  },
  "metrics": {
    "total_recipients": 5200,
    "total_sent":       5200,
    "total_delivered":  5096,
    "total_opened":     2038,
    "total_clicked":    510,
    "total_bounced":    104,
    "total_complained": 5,
    "total_unsubscribed":18,
    "open_rate":        0.392,
    "click_rate":       0.098,
    "bounce_rate":      0.020
  },
  "timeline": [
    { "hour": "2026-04-01T09:00:00Z", "opens": 820, "clicks": 205 },
    { "hour": "2026-04-01T10:00:00Z", "opens": 614, "clicks": 153 }
  ]
}

POST /api/v1/track/event

Track a custom event tied to a contact. Useful for measuring downstream conversions from email clicks.

curl -X POST https://api.misar.io/mail/v1/track/event \
  -H "Authorization: Bearer msk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name":    "trial_started",
    "contact_email": "[email protected]",
    "properties": {
      "plan":    "pro",
      "source":  "welcome_email"
    }
  }'

Request Fields

| Field | Type | Required | Notes | |-------|------|----------|-------| | event_name | string | ✓ | Snake_case event name | | contact_email | string | ✓ | Email of the contact who triggered the event | | properties | object | — | Arbitrary key-value metadata | | timestamp | string | — | ISO 8601 — defaults to now |

Response

{ "success": true, "event_id": "evt_xyz789" }

POST /api/v1/track/purchase

Requires Max plan — ecommerce and revenue tracking is a Max-tier feature.

Track a purchase event with revenue data. Revenue is attributed to the last clicked campaign within 7 days.

curl -X POST https://api.misar.io/mail/v1/track/purchase \
  -H "Authorization: Bearer msk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_email": "[email protected]",
    "amount":        99.99,
    "currency":      "USD",
    "order_id":      "order_12345",
    "items": [
      { "name": "Pro Plan", "quantity": 1, "price": 99.99 }
    ]
  }'

Request Fields

| Field | Type | Required | Notes | |-------|------|----------|-------| | contact_email | string | ✓ | Purchasing contact | | amount | number | ✓ | Total order value | | currency | string | ✓ | ISO 4217 currency code (e.g. USD, INR) | | order_id | string | — | Your system's order ID (deduplication key) | | items | array | — | Line items with name, quantity, price |

Response

{
  "success":  true,
  "event_id": "evt_purchase_abc",
  "attributed_campaign_id": "camp_abc123"
}

attributed_campaign_id is null if no clicked campaign was found within the attribution window.