Dokumentacja / API Reference

Analytics API

3 min czytania

API Analytics zapewnia dostęp do statystyk email, metryk dostarczalności i danych o zaangażowaniu.

Pobierz statystyki ogólne

Pobierz statystyki wysokiego poziomu dla Twojego konta.

GET /v1/analytics/overview

Parametry zapytania

Parametr Typ Opis
from string Data początkowa (ISO 8601)
to string Data końcowa (ISO 8601)

Przykładowe żądanie

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

Odpowiedź

{
  "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
  }
}

Pobierz dane szeregu czasowego

Pobierz statystyki pogrupowane po okresie czasu.

GET /v1/analytics/timeseries

Parametry zapytania

Parametr Typ Opis
from string Data początkowa (ISO 8601)
to string Data końcowa (ISO 8601)
group_by string hour, day, week, month
metrics string Rozdzielone przecinkami: sent, delivered, opened, etc.

Przykładowe żądanie

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

Odpowiedź

{
  "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
    }
  ]
}

Pobierz statystyki dostarczalności

Pobierz szczegółowe metryki dostarczalności.

GET /v1/analytics/deliverability

Parametry zapytania

Parametr Typ Opis
from string Data początkowa
to string Data końcowa

Przykładowe żądanie

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

Odpowiedź

{
  "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
    }
  }
}

Pobierz statystyki zaangażowania

Pobierz metryki otwarć i kliknięć.

GET /v1/analytics/engagement

Parametry zapytania

Parametr Typ Opis
from string Data początkowa
to string Data końcowa
group_by string hour, day, week, month

Przykładowe żądanie

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

Odpowiedź

{
  "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
  }
}

Pobierz wynik reputacji

Pobierz metryki reputacji nadawcy.

GET /v1/analytics/reputation

Przykładowe żądanie

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

Odpowiedź

{
  "domain": "notifications.twojadomena.pl",
  "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"]
  }
}

Poziomy reputacji

Wynik Poziom
90-100 Doskonała
75-89 Dobra
50-74 Średnia
25-49 Słaba
0-24 Krytyczna

Pobierz statystyki po tagach

Pobierz statystyki filtrowane po tagach wiadomości.

GET /v1/analytics/tags

Parametry zapytania

Parametr Typ Opis
from string Data początkowa
to string Data końcowa
tags string Lista tagów rozdzielona przecinkami

Przykładowe żądanie

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

Odpowiedź

{
  "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
      }
    }
  ]
}

Pobierz rozbicie odbić

Pobierz szczegółową analizę odbić.

GET /v1/analytics/bounces

Parametry zapytania

Parametr Typ Opis
from string Data początkowa
to string Data końcowa
type string hard, soft, lub oba

Przykładowe żądanie

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

Odpowiedź

{
  "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": "starafirma.pl", "count": 38},
    {"domain": "nieistniejaca.domena", "count": 30}
  ]
}

Eksportuj analitykę

Eksportuj dane analityczne do CSV.

POST /v1/analytics/export

Body żądania

Pole Typ Wymagane Opis
from string Tak Data początkowa
to string Tak Data końcowa
type string Tak overview, messages, bounces
format string Nie csv (domyślnie) lub json

Przykładowe żądanie

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"
  }'

Odpowiedź

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

Pobierz status eksportu

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"
}

Kody błędów

Kod Opis
invalid_date_range Nieprawidłowy lub brakujący zakres dat
date_range_too_large Maksymalnie 90 dni na żądanie
export_not_found ID eksportu nie znalezione
export_expired Link do pobrania wygasł