Domains API

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
name	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 '{"name": "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"}
}

---

Zaktualizuj ustawienia śledzenia

Ustawia domyślne śledzenie dla całej domeny. Działa jak wyłącznik nadrzędny: przy tracking_enabled: false żadna wiadomość z tej domeny nie dostanie pixela ani przepisanych linków, niezależnie od pola tracking w pojedynczej wysyłce.

PATCH /v1/domains/{domain_id}

Body żądania

Pole	Typ	Opis
tracking_enabled	boolean	Główny przełącznik śledzenia dla domeny
click_tracking	boolean	Domyślne śledzenie kliknięć (przepisywanie linków)
open_tracking	boolean	Domyślne śledzenie otwarć (pixel)

Aktualizacja jest częściowa — pola pominięte zachowują dotychczasową wartość. Aktualizowalne są wyłącznie te trzy pola; cokolwiek innego w body (name, status, ownership_verified, …) jest ignorowane. Wartość niebędąca wartością logiczną kończy się błędem 400.

Przykładowe żądanie

curl -X PATCH https://api.mailingapi.com/v1/domains/dom_abc123 \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tracking_enabled": false }'

Odpowiedź

{
  "data": {
    "id": "dom_abc123",
    "name": "mail.twojadomena.pl",
    "tracking": {
      "enabled": false,
      "click_tracking": true,
      "open_tracking": true
    }
  }
}

Kiedy używać tego zamiast tracking per wiadomość: jeśli Twój produkt wysyła wyłącznie pocztę transakcyjną — zaproszenia, resety haseł, powiadomienia systemowe — wyłącz śledzenie raz tutaj, zamiast pamiętać o polu przy każdej wysyłce. Pominięte pole w wysyłce oznacza „użyj domyślnych domeny”, więc zapomniana flaga zachowuje się wtedy bezpiecznie, zamiast cicho wysłać pixel. Patrz Wiadomości → Opcje śledzenia.

---

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

---

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