Dokumentacja / API Reference

Domains API

2 min czytania

API Domains pozwala dodawać, weryfikować i zarządzać domenami wysyłkowymi.

Dodaj domenę

Zarejestruj nową domenę wysyłkową.

POST /v1/domains

Body żądania

Pole Typ Wymagane Opis
domain string Tak Nazwa domeny (np. mail.twojadomena.pl)

Przykładowe żądanie

curl -X POST https://api.mailingapi.com/v1/domains \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "notifications.twojadomena.pl"}'

Odpowiedź

{
  "id": "dom_abc123",
  "domain": "notifications.twojadomena.pl",
  "status": "pending",
  "created_at": "2024-01-15T10:00:00Z",
  "dns_records": [
    {
      "type": "TXT",
      "host": "notifications.twojadomena.pl",
      "value": "v=spf1 include:spf.mailingapi.com ~all",
      "purpose": "spf",
      "status": "pending"
    },
    {
      "type": "CNAME",
      "host": "mlapi._domainkey.notifications.twojadomena.pl",
      "value": "mlapi._domainkey.mailingapi.com",
      "purpose": "dkim",
      "status": "pending"
    },
    {
      "type": "TXT",
      "host": "_dmarc.notifications.twojadomena.pl",
      "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@twojadomena.pl",
      "purpose": "dmarc",
      "status": "pending"
    },
    {
      "type": "TXT",
      "host": "_mailingapi.notifications.twojadomena.pl",
      "value": "mailingapi-verify=abc123xyz",
      "purpose": "ownership",
      "status": "pending"
    }
  ]
}

Lista domen

Pobierz wszystkie domeny dla Twojego konta.

GET /v1/domains

Przykładowe żądanie

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

Odpowiedź

{
  "data": [
    {
      "id": "dom_abc123",
      "domain": "notifications.twojadomena.pl",
      "status": "verified",
      "created_at": "2024-01-15T10:00:00Z"
    },
    {
      "id": "dom_def456",
      "domain": "alerts.twojadomena.pl",
      "status": "pending",
      "created_at": "2024-01-16T10:00:00Z"
    }
  ]
}

Pobierz domenę

Pobierz szczegóły konkretnej domeny.

GET /v1/domains/{domain_id}

Przykładowe żądanie

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

Odpowiedź

{
  "id": "dom_abc123",
  "domain": "notifications.twojadomena.pl",
  "status": "verified",
  "created_at": "2024-01-15T10:00:00Z",
  "verified_at": "2024-01-15T10:30:00Z",
  "authentication": {
    "spf": {"status": "valid"},
    "dkim": {"status": "valid"},
    "dmarc": {"status": "valid"},
    "ownership": {"status": "valid"}
  }
}

Statusy domeny

Status Opis
pending Rekordy DNS jeszcze nie zweryfikowane
verifying Weryfikacja w toku
verified Wszystkie rekordy prawidłowe, gotowe do wysyłki
failed Jeden lub więcej rekordów nieprawidłowych

Pobierz rekordy DNS

Pobierz rekordy DNS wymagane do weryfikacji domeny.

GET /v1/domains/{domain_id}/dns-records

Przykładowe żądanie

curl https://api.mailingapi.com/v1/domains/dom_abc123/dns-records \
  -H "Authorization: Bearer $API_KEY"

Odpowiedź

{
  "records": [
    {
      "type": "TXT",
      "host": "notifications.twojadomena.pl",
      "value": "v=spf1 include:spf.mailingapi.com ~all",
      "purpose": "spf",
      "status": "valid"
    },
    {
      "type": "CNAME",
      "host": "mlapi._domainkey.notifications.twojadomena.pl",
      "value": "mlapi._domainkey.mailingapi.com",
      "purpose": "dkim",
      "status": "valid"
    },
    {
      "type": "TXT",
      "host": "_dmarc.notifications.twojadomena.pl",
      "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@twojadomena.pl",
      "purpose": "dmarc",
      "status": "valid"
    },
    {
      "type": "TXT",
      "host": "_mailingapi.notifications.twojadomena.pl",
      "value": "mailingapi-verify=abc123xyz",
      "purpose": "ownership",
      "status": "valid"
    }
  ]
}

Zweryfikuj domenę

Wywołaj weryfikację rekordów DNS.

POST /v1/domains/{domain_id}/verify

Przykładowe żądanie

curl -X POST https://api.mailingapi.com/v1/domains/dom_abc123/verify \
  -H "Authorization: Bearer $API_KEY"

Odpowiedź (sukces)

{
  "id": "dom_abc123",
  "domain": "notifications.twojadomena.pl",
  "status": "verified",
  "spf": {"status": "valid"},
  "dkim": {"status": "valid"},
  "dmarc": {"status": "valid"},
  "ownership": {"status": "valid"}
}

Odpowiedź (częściowy błąd)

{
  "id": "dom_abc123",
  "domain": "notifications.twojadomena.pl",
  "status": "failed",
  "spf": {"status": "valid"},
  "dkim": {"status": "missing", "error": "CNAME record not found"},
  "dmarc": {"status": "valid"},
  "ownership": {"status": "valid"}
}

Usuń domenę

Usuń domenę z Twojego konta.

DELETE /v1/domains/{domain_id}

Przykładowe żądanie

curl -X DELETE https://api.mailingapi.com/v1/domains/dom_abc123 \
  -H "Authorization: Bearer $API_KEY"

Odpowiedź

204 No Content

Ostrzeżenie: Usunięcie domeny spowoduje:

  • Unieważnienie wszystkich powiązanych kluczy API
  • Zablokowanie wysyłki z tej domeny
  • Usunięcie historycznych statystyk

Statystyki domeny

Pobierz statystyki wysyłki dla domeny.

GET /v1/domains/{domain_id}/stats

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

Przykładowe żądanie

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

Odpowiedź

{
  "domain": "notifications.twojadomena.pl",
  "period": {
    "from": "2024-01-01",
    "to": "2024-01-31"
  },
  "totals": {
    "sent": 15000,
    "delivered": 14850,
    "bounced": 100,
    "complained": 5,
    "opened": 3500,
    "clicked": 875
  },
  "rates": {
    "delivery": 99.0,
    "bounce": 0.67,
    "complaint": 0.03,
    "open": 23.6,
    "click": 5.9
  }
}

Kody błędów

Kod Opis
domain_already_exists Domena już zarejestrowana
invalid_domain Nieprawidłowy format domeny
domain_not_found ID domeny nie znalezione
verification_failed Weryfikacja DNS nie powiodła się
domain_in_use Nie można usunąć domeny z aktywnymi kluczami API