Konfiguracja domeny - Dokumentacja

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

Przejdź do Ustawienia → Domeny
Kliknij Dodaj domenę
Wpisz domenę (np. notifications.twojadomena.pl)
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

5. Rekord MX (opcjonalny)

MX umożliwia odbieranie emaili przez MailingAPI (inbound processing, bounce handling po stronie MTA). Pomiń ten krok jeśli używasz domeny tylko do wysyłki.

Typ: MX
Host: notifications.twojadomena.pl
Priorytet: 10
Wartość: mx.outboxa.com

Uwaga: Jeśli domena ma już MX (np. wskazujący na Google Workspace / Microsoft 365), nie zastępuj go — odbierałbyś pocztę firmową w MailingAPI zamiast w swojej skrzynce. W takim przypadku użyj dedykowanej subdomeny dla wysyłki (np. notifications.twojadomena.pl), która nie ma innego MX.

6. Tracking CNAME i automatyczny SSL

Tracking CNAME zmienia domenę, pod którą wychodzą linki trackingowe (otwarcia, kliknięcia, unsubscribe) z api.mailingapi.com na Twoją subdomenę t.twojadomena.pl. To znacząco poprawia dostarczalność — linki i sender alignment pod jedną marką eliminują sygnały “mismatch” u filtrów antyspamowych (Gmail, Outlook, Mimecast).

Typ: CNAME
Host: t.notifications.twojadomena.pl
Wartość: api.mailingapi.com

Prefix t. jest wymagany — dokładnie ten prefix MailingAPI wstrzykuje do linków w Twoich mailach i on routuje ruch na naszą infrastrukturę SSL.

Automatyczne wystawienie certyfikatu SSL

Po udanej weryfikacji CNAME (zwykle <60 s od dodania w DNS) MailingAPI automatycznie uzyskuje darmowy certyfikat Let’s Encrypt dla t.twojadomena.pl. Nie musisz nic klikać, wgrywać ani kopiować kluczy prywatnych.

Proces:

Weryfikacja CNAME (Ty) — dodaj rekord i kliknij “Zweryfikuj”
ACME HTTP-01 challenge (automat) — Let’s Encrypt pyta naszą infrastrukturę o dowód kontroli nad domeną, my odpowiadamy
Wystawienie certyfikatu (automat) — cert ląduje w naszej bazie, szyfrowany, dostępny dla TLS handshake
Runtime SNI loading — każde żądanie do https://t.twojadomena.pl używa tego certu

Całość zwykle <2 minuty od weryfikacji. W panelu (Ustawienia → Domeny → [Twoja Domena]) zobaczysz:

🟡 Provisioning SSL certificate... — w trakcie (max kilka minut)
🟢 SSL certificate active — gotowe, linki https://t.twojadomena.pl/c/... działają

Renewal

Certyfikaty Let’s Encrypt są ważne 90 dni. MailingAPI odnawia je automatycznie codziennie (dla każdego certu <30 dni do wygaśnięcia). Nie ma żadnej akcji po Twojej stronie — dopóki CNAME pozostaje prawidłowy.

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

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

OVH

Przejdź do Strefy DNS
Kliknij Dodaj wpis
Wybierz typ rekordu
Wpisz subdomenę i cel
Zatwierdź

home.pl

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

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

Weryfikacja domeny

Po dodaniu rekordów DNS:

Przez Dashboard

Przejdź do Ustawienia → Domeny → [Twoja Domena]
Kliknij Zweryfikuj
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=)

HTTPS tracking nie działa po kilku minutach

Jeśli w panelu widzisz Provisioning SSL certificate... dłużej niż ~10 minut:

Sprawdź CNAME propagation — dig t.twojadomena.pl CNAME powinno zwrócić api.mailingapi.com. Niektórzy rejestratorzy DNS (zwłaszcza tanie) propagują do 48 h.
CAA records — jeśli masz rekord CAA na domenie głównej (twojadomena.pl), upewnij się że zawiera 0 issue "letsencrypt.org" albo go usuń. CAA blokuje Let’s Encrypt.
Let’s Encrypt rate limit — limit 50 certów tygodniowo na zarejestrowaną domenę (eTLD+1). Jeśli przekroczyłeś limit eksperymentując z wieloma subdomenami, poczekaj do resetu.
Zgłoś przez support — jeśli powyższe nie pomaga, logi provisioning workera zawierają szczegóły błędu ACME.

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

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

Następne kroki

Skonfiguruj webhooki dla powiadomień o dostarczeniu
Twórz szablony dla spójnych emaili
Skonfiguruj walidację by czyścić listy