Dokumentacja / Przewodniki

Konfiguracja domeny

3 min czytania

Przed wysyłką emaili w produkcji musisz zweryfikować domenę. To dowodzi, że jesteś właścicielem domeny i pozwala serwerom email ufać Twoim wiadomościom.

Dlaczego weryfikacja domeny ma znaczenie

Bez weryfikacji:

  • Emaile mogą lądować w spamie
  • Niektórzy dostawcy całkowicie odrzucają wiadomości
  • Nie możesz używać własnego brandingu
  • Dostarczalność jest nieprzewidywalna

Z weryfikacją:

  • SPF, DKIM, DMARC uwierzytelniają Twoje emaile
  • Wyższe wskaźniki dostarczenia do inbox
  • Profesjonalna reputacja nadawcy
  • Pełna kontrola nad tożsamością email

Dodawanie domeny

Przez Dashboard

  1. Przejdź do Ustawienia → Domeny
  2. Kliknij Dodaj domenę
  3. Wpisz domenę (np. notifications.twojadomena.pl)
  4. Kliknij Dodaj

Przez API

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",
  "dns_records": [...]
}

Wybór domeny

Użyj subdomeny

Zalecamy używanie subdomeny zamiast domeny głównej:

✓ mail.twojadomena.pl
✓ notifications.twojadomena.pl
✓ alerts.twojadomena.pl
✗ twojadomena.pl (niezalecane)

Dlaczego?

  • Izoluje reputację email od strony www
  • Łatwiejsze zarządzanie rekordami DNS
  • Osobne domeny dla transakcyjnych vs. marketingowych

Konwencje nazewnictwa

Zastosowanie Przykład
Emaile transakcyjne mail.twojadomena.pl
Powiadomienia notifications.twojadomena.pl
Alerty alerts.twojadomena.pl
Marketing (osobno) news.twojadomena.pl

Rekordy DNS

Po dodaniu domeny otrzymasz rekordy DNS do konfiguracji:

1. Rekord SPF

SPF mówi serwerom email, które IP mogą wysyłać z Twojej domeny.

Typ: TXT
Host: notifications.twojadomena.pl
Wartość: v=spf1 include:spf.mailingapi.com ~all

Jeśli masz już rekord SPF, dodaj nasz include:

v=spf1 include:_spf.google.com include:spf.mailingapi.com ~all

Ważne: Możesz mieć tylko jeden rekord SPF per domena.

2. Rekord DKIM

DKIM podpisuje emaile kryptograficznie, dowodząc że nie zostały zmodyfikowane.

Typ: CNAME
Host: mlapi._domainkey.notifications.twojadomena.pl
Wartość: mlapi._domainkey.mailingapi.com

Automatycznie zarządzamy rotacją kluczy gdy używasz CNAME.

3. Rekord DMARC

DMARC mówi odbiorcom co robić z emailami które nie przeszły SPF/DKIM.

Typ: TXT
Host: _dmarc.notifications.twojadomena.pl
Wartość: v=DMARC1; p=quarantine; rua=mailto:dmarc@twojadomena.pl

Polityki DMARC:

  • p=none — Tylko monitorowanie, brak akcji
  • p=quarantine — Wysyłaj niepowodzenia do spamu
  • p=reject — Całkowicie odrzucaj niepowodzenia

Zacznij od p=none, potem zaostrz po potwierdzeniu że wszystko działa.

4. Weryfikacja własności

Rekord TXT potwierdzający że kontrolujesz tę domenę:

Typ: TXT
Host: _mailingapi.notifications.twojadomena.pl
Wartość: mailingapi-verify=abc123xyz

Pobieranie rekordów DNS

Przez Dashboard

Przejdź do Ustawienia → Domeny → [Twoja Domena] → Rekordy DNS

Przez API

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"
    },
    {
      "type": "CNAME",
      "host": "mlapi._domainkey.notifications.twojadomena.pl",
      "value": "mlapi._domainkey.mailingapi.com",
      "purpose": "dkim"
    }
  ]
}

Dodawanie rekordów w DNS

Proces różni się w zależności od dostawcy. Oto popularne:

Cloudflare

  1. Przejdź do ustawień DNS
  2. Kliknij Add record
  3. Wybierz typ rekordu (TXT lub CNAME)
  4. Wpisz nazwę i wartość
  5. Zapisz (proxy OFF dla rekordów email)

OVH

  1. Przejdź do Strefy DNS
  2. Kliknij Dodaj wpis
  3. Wybierz typ rekordu
  4. Wpisz subdomenę i cel
  5. Zatwierdź

home.pl

  1. Przejdź do Panel → Domeny → Zarządzaj DNS
  2. Kliknij Dodaj rekord
  3. Wybierz typ i wypełnij dane
  4. Zapisz

Uwaga: Zmiany DNS mogą propagować do 48 godzin, choć zwykle jest znacznie szybciej.

Weryfikacja domeny

Po dodaniu rekordów DNS:

Przez Dashboard

  1. Przejdź do Ustawienia → Domeny → [Twoja Domena]
  2. Kliknij Zweryfikuj
  3. Poczekaj na weryfikację (zwykle sekundy do minut)

Przez API

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

Odpowiedź:

{
  "status": "verified",
  "spf": {"status": "valid"},
  "dkim": {"status": "valid"},
  "dmarc": {"status": "valid"},
  "ownership": {"status": "valid"}
}

Statusy weryfikacji

Status Znaczenie
pending Rekordy DNS jeszcze nie sprawdzone
verifying Weryfikacja w toku
verified Wszystkie rekordy poprawne, gotowe do wysyłki
failed Jeden lub więcej rekordów niepoprawnych

Jeśli weryfikacja się nie powiedzie, sprawdź odpowiedź po szczegółowe błędy:

{
  "status": "failed",
  "spf": {"status": "valid"},
  "dkim": {"status": "missing", "error": "CNAME record not found"},
  "dmarc": {"status": "valid"},
  "ownership": {"status": "valid"}
}

Rozwiązywanie problemów

“SPF record not found”

  • Zweryfikuj czy rekord TXT istnieje pod poprawnym hostem
  • Sprawdź literówki w wartości
  • Poczekaj na propagację DNS

“Too many DNS lookups”

SPF ma limit 10 zapytań DNS. Jeśli przekraczasz:

  • Usuń nieużywane include
  • Użyj adresów IP bezpośrednio dla statycznych serwerów
  • Rozważ SPF flattening

“DKIM signature mismatch”

  • Upewnij się że CNAME wskazuje dokładnie na mlapi._domainkey.mailingapi.com
  • Sprawdź czy host to mlapi._domainkey.twojadomena.pl
  • Usuń końcowe kropki

“DMARC not aligned”

  • Upewnij się że domeny SPF i DKIM pasują do adresu From
  • Sprawdź czy polityka DMARC pozwala subdomenom (tag sp=)

Wiele domen

Możesz dodać wiele domen do konta:

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

Każda domena:

  • Wymaga osobnej weryfikacji
  • Otrzymuje własne klucze API
  • Ma niezależną reputację

Zastosowania:

  • Różne produkty/marki
  • Oddzielenie transakcyjnych od marketingowych
  • Domeny regionalne

Dobre praktyki

  1. Używaj subdomen — Nie ryzykuj reputacji domeny głównej
  2. Zacznij od monitorującego DMARC — Użyj p=none na początek
  3. Sprawdzaj rekordy regularnie — DNS może się zmienić lub wygasnąć
  4. Monitoruj dostarczalność — Używaj analityki w dashboardzie
  5. Rozdzielaj typy emaili — Różne domeny do różnych celów

Następne kroki