Analytics API - Documentation

The Analytics API provides access to email statistics, deliverability metrics, and engagement data.

Get overview stats

Get high-level statistics for your account.

GET /v1/analytics/overview

Query parameters

Parameter	Type	Description
`from`	string	Start date (ISO 8601)
`to`	string	End date (ISO 8601)

Example request

curl "https://api.mailingapi.com/v1/analytics/overview?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "period": {
    "from": "2024-01-01",
    "to": "2024-01-31"
  },
  "totals": {
    "sent": 50000,
    "delivered": 49200,
    "bounced": 500,
    "rejected": 300,
    "complaints": 15,
    "opens": 12300,
    "unique_opens": 9800,
    "clicks": 1845,
    "unique_clicks": 1520,
    "unsubscribes": 45
  },
  "rates": {
    "delivery": 98.4,
    "bounce": 1.0,
    "complaint": 0.03,
    "open": 25.0,
    "click": 3.75,
    "unsubscribe": 0.09
  }
}

Get time series data

Get statistics grouped by time period.

GET /v1/analytics/timeseries

Query parameters

Parameter	Type	Description
`from`	string	Start date (ISO 8601)
`to`	string	End date (ISO 8601)
`group_by`	string	`hour`, `day`, `week`, `month`
`metrics`	string	Comma-separated: `sent`, `delivered`, `opened`, etc.

Example request

curl "https://api.mailingapi.com/v1/analytics/timeseries?from=2024-01-01&to=2024-01-07&group_by=day" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "period": {
    "from": "2024-01-01",
    "to": "2024-01-07"
  },
  "group_by": "day",
  "data": [
    {
      "date": "2024-01-01",
      "sent": 7500,
      "delivered": 7400,
      "bounced": 60,
      "opened": 1850,
      "clicked": 280
    },
    {
      "date": "2024-01-02",
      "sent": 8200,
      "delivered": 8100,
      "bounced": 70,
      "opened": 2100,
      "clicked": 315
    }
  ]
}

Get deliverability stats

Get detailed deliverability metrics.

GET /v1/analytics/deliverability

Query parameters

Parameter	Type	Description
`from`	string	Start date
`to`	string	End date

Example request

curl "https://api.mailingapi.com/v1/analytics/deliverability?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "period": {
    "from": "2024-01-01",
    "to": "2024-01-31"
  },
  "delivery": {
    "sent": 50000,
    "delivered": 49200,
    "delivery_rate": 98.4
  },
  "bounces": {
    "total": 500,
    "hard": 350,
    "soft": 150,
    "bounce_rate": 1.0
  },
  "complaints": {
    "total": 15,
    "complaint_rate": 0.03
  },
  "rejections": {
    "total": 300,
    "reasons": {
      "invalid_recipient": 180,
      "domain_not_verified": 80,
      "rate_limited": 40
    }
  }
}

Get engagement stats

Get open and click metrics.

GET /v1/analytics/engagement

Query parameters

Parameter	Type	Description
`from`	string	Start date
`to`	string	End date
`group_by`	string	`hour`, `day`, `week`, `month`

Example request

curl "https://api.mailingapi.com/v1/analytics/engagement?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "period": {
    "from": "2024-01-01",
    "to": "2024-01-31"
  },
  "opens": {
    "total": 12300,
    "unique": 9800,
    "rate": 25.0,
    "by_device": {
      "desktop": 4500,
      "mobile": 7200,
      "tablet": 600
    },
    "by_client": {
      "gmail": 3500,
      "outlook": 2800,
      "apple_mail": 2000,
      "other": 1500
    }
  },
  "clicks": {
    "total": 1845,
    "unique": 1520,
    "rate": 3.75,
    "click_to_open_rate": 15.5
  }
}

Get reputation score

Get your sender reputation metrics.

GET /v1/analytics/reputation

Example request

curl https://api.mailingapi.com/v1/analytics/reputation \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "domain": "notifications.yourdomain.com",
  "reputation": {
    "score": 92,
    "level": "excellent",
    "trend": "stable"
  },
  "factors": {
    "authentication": {
      "status": "pass",
      "spf": "pass",
      "dkim": "pass",
      "dmarc": "pass"
    },
    "bounce_rate": {
      "status": "good",
      "value": 1.0,
      "threshold": 2.0
    },
    "complaint_rate": {
      "status": "excellent",
      "value": 0.03,
      "threshold": 0.1
    },
    "engagement": {
      "status": "good",
      "open_rate": 25.0,
      "click_rate": 3.75
    }
  },
  "blacklists": {
    "listed": false,
    "checked": ["spamhaus", "barracuda", "sorbs"]
  }
}

Reputation levels

Score	Level
90-100	Excellent
75-89	Good
50-74	Fair
25-49	Poor
0-24	Critical

Get stats by tag

Get statistics filtered by message tags.

GET /v1/analytics/tags

Query parameters

Parameter	Type	Description
`from`	string	Start date
`to`	string	End date
`tags`	string	Comma-separated tag list

Example request

curl "https://api.mailingapi.com/v1/analytics/tags?from=2024-01-01&to=2024-01-31&tags=welcome,onboarding" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "period": {
    "from": "2024-01-01",
    "to": "2024-01-31"
  },
  "tags": [
    {
      "tag": "welcome",
      "sent": 5000,
      "delivered": 4950,
      "opened": 2100,
      "clicked": 850,
      "rates": {
        "delivery": 99.0,
        "open": 42.4,
        "click": 17.2
      }
    },
    {
      "tag": "onboarding",
      "sent": 4500,
      "delivered": 4450,
      "opened": 1800,
      "clicked": 720,
      "rates": {
        "delivery": 98.9,
        "open": 40.4,
        "click": 16.2
      }
    }
  ]
}

Get bounce breakdown

Get detailed bounce analysis.

GET /v1/analytics/bounces

Query parameters

Parameter	Type	Description
`from`	string	Start date
`to`	string	End date
`type`	string	`hard`, `soft`, or both

Example request

curl "https://api.mailingapi.com/v1/analytics/bounces?from=2024-01-01&to=2024-01-31" \
  -H "Authorization: Bearer $API_KEY"

Response

{
  "period": {
    "from": "2024-01-01",
    "to": "2024-01-31"
  },
  "total": 500,
  "by_type": {
    "hard": 350,
    "soft": 150
  },
  "by_reason": {
    "user_not_found": 200,
    "mailbox_full": 120,
    "domain_not_found": 80,
    "blocked": 60,
    "other": 40
  },
  "top_domains": [
    {"domain": "example.com", "count": 45},
    {"domain": "oldcompany.com", "count": 38},
    {"domain": "invalid.domain", "count": 30}
  ]
}

Export analytics

Export analytics data to CSV.

POST /v1/analytics/export

Request body

Field	Type	Required	Description
`from`	string	Yes	Start date
`to`	string	Yes	End date
`type`	string	Yes	`overview`, `messages`, `bounces`
`format`	string	No	`csv` (default) or `json`

Example request

curl -X POST https://api.mailingapi.com/v1/analytics/export \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "2024-01-01",
    "to": "2024-01-31",
    "type": "messages",
    "format": "csv"
  }'

Response

{
  "export_id": "exp_abc123",
  "status": "processing",
  "download_url": null
}

Get export status

curl https://api.mailingapi.com/v1/analytics/export/exp_abc123 \
  -H "Authorization: Bearer $API_KEY"

{
  "export_id": "exp_abc123",
  "status": "completed",
  "download_url": "https://api.mailingapi.com/v1/analytics/export/exp_abc123/download",
  "expires_at": "2024-01-22T10:00:00Z"
}

Error codes

Code	Description
`invalid_date_range`	Invalid or missing date range
`date_range_too_large`	Maximum 90 days per request
`export_not_found`	Export ID not found
`export_expired`	Download link has expired