Domeny wysyłkowe
Zanim będziemy mogli dostarczać e-maile z Twojej domeny, musisz udowodnić, że jesteś jej właścicielem, i opublikować rekordy DNS umożliwiające dostawcom skrzynek pocztowych uwierzytelnianie Twojej poczty. Domena wysyłkowa to zasób w zakresie obszaru roboczego (dom_...), który śledzi tę konfigurację: jakie rekordy opublikować, co zostało zweryfikowane i czy domena jest gotowa do wysyłania.
Współdzielenie domeny między organizacjami
Ta sama domena może być zarejestrowana przez więcej niż jedną organizację bez wzajemnych konfliktów. Każda organizacja potwierdza własność za pomocą własnego klucza DKIM, więc:
- Inna organizacja korzystająca z tej samej domeny nigdy nie zobaczy Twojego stanu weryfikacji ani nie zmieni Twojej konfiguracji.
- Każdy region (us1, eu1) jest niezależny: ta sama domena w dwóch regionach to dwie osobne rejestracje z własnymi rekordami DNS. Zarejestruj ją w każdym regionie, z którego wysyłasz.
Rejestracja domeny
Utwórz domenę za pomocą POST /v1/email/domains. Wywołanie działa w zakresie obszaru roboczego i przyjmuje domenę wysyłkową oraz opcjonalne etykiety dla nazw hostów return-path i trackingu. Podaj tylko etykietę (send, links), a my złożymy pełną nazwę hosta w ramach Twojej domeny wysyłkowej. Pominięte wartości przyjmują domyślnie send i links.
Używaj dedykowanej subdomeny (mail.acme.com) zamiast domeny zarejestrowanej. Dzięki temu reputacja wysyłkowa jest oddzielona od wszystkiego innego w domenie, a wszystkie rekordy, o których publikację prosimy, nie trafiają do apeksu Twojej strefy. Ten drugi powód jest kluczowy: rekord MX do odbierania znajduje się pod tą samą nazwą co rekordy MX obsługujące pocztę Twojej firmy, więc publikacja go na domenie wysyłkowej będącej apeksem przekieruje tę pocztę do nas.
const domain = await bird.domains.create({ domain: "mail.acme.com" });
console.log(domain.id, domain.status); // "dom_…", "pending"domain = client.domains.create(domain="mail.acme.com")
print(domain.id, domain.status)domain, err := client.Domains.Create(context.Background(), bird.DomainCreateParams{
Domain: "mail.acme.com",
})
if err != nil {
log.Fatal(err)
}
fmt.Println(domain.Id, *domain.Status)$domain = $bird->domains->create(
(new DomainCreate())->setDomain('mail.acme.com'),
);
echo $domain->getId(), ' ', $domain->getStatus(); // "dom_…", "pending"bird email domains create mail.acme.com{
"name": "email_domains_create",
"arguments": {
"domain": "mail.acme.com"
}
}curl -s https://eu1.platform.bird.com/v1/email/domains \
-H "Authorization: Bearer $BIRD_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"domain": "mail.acme.com",
"return_path": { "name": "send" },
"tracking": { "name": "links" }
}'Odpowiedź zawiera status: pending, selektor DKIM przypisany do Twojej organizacji oraz dns_records do opublikowania. Istniejąca rejestracja w obszarze roboczym zwraca 409. Przekroczenie limitu domen organizacji zwraca 422. Zamień eu1 na us1 w przypadku obszaru roboczego w USA. Klucze API używają tych samych prefiksów regionalnych: bk_eu1_... i bk_us1_.... Domenami możesz też zarządzać w Email > Domains.
Publikacja rekordów DNS
Tablica dns_records udostępnia gotowe do skopiowania name, host i value dla każdego rekordu. Niektórzy dostawcy odrzucają długą wartość TXT DKIM jako pojedynczy ciąg znaków; narzędzie do dzielenia rekordów DNS rozbija ją na cytowane ciągi, których ci dostawcy oczekują. Co publikujesz:
| Rekord | Typ | Wymagany do wysyłania | Co robi |
|---|---|---|---|
| DKIM | TXT | Tak | Potwierdza własność i podpisuje Twoją pocztę kluczem organizacji |
| Return-path CNAME | CNAME | Tak | Kieruje zwrotki do nas i obejmuje SPF; wyszukiwanie SPF podąża za CNAME, więc rekord SPF w apeksie Twojej domeny nie jest potrzebny |
| DMARC | TXT | Tak | Dowolna prawidłowa polityka v=DMARC1 obejmująca domenę wysyłkową, ustawiona na samej domenie lub na jej domenie zarejestrowanej (organizacyjnej). Wystarczy minimalna polityka p=none. |
| Tracking CNAME | CNAME | Nie | Włącza brandowane nazwy hostów do śledzenia otwarć i kliknięć; śledzone linki są serwowane przez HTTPS po weryfikacji |
| Inbound MX | MX | Nie | Kieruje pocztę dla domeny do nas w celu odbierania. Ma status optional: true, dopóki nie włączysz odbierania; jego opublikowanie zastępuje rekordy MX aktualnie używane przez domenę. |
Informacje o przeznaczeniu i wartościach każdego rekordu znajdziesz w DKIM, SPF i DMARC. Rekordy MX do odbierania znajdują się w dns_records z purpose: inbound_mx, gdy odbieranie jest dostępne w Twoim regionie, i mają status optional: true, dopóki nie włączysz odbierania na domenie. Pomiń każdy rekord oznaczony optional, chyba że chcesz skorzystać z funkcji, którą włącza. Instrukcje konfiguracji u dostawcy DNS znajdziesz w przewodnikach Cloudflare, Route 53 lub ogólnym dla rejestratorów.
Dashboard wykrywa obsługiwanych dostawców DNS na podstawie serwerów nazw Twojej domeny i linkuje do ich ustawień DNS. Otwórz Email > Domains, a następnie wybierz domenę, aby wyświetlić jej rekordy. Jeśli ktoś inny zarządza Twoim DNS, funkcja POST /v1/email/domains/{domain_id}/dns-records/share wyśle mu e-mailem rekordy do opublikowania.
Cykl życia weryfikacji
Nowa domena zaczyna ze statusem pending. Nie musisz odpytywać, bo sprawdzamy Twoje rekordy automatycznie. Sprawdzenia rozpoczynają się natychmiast po rejestracji i przechodzą od co kilka minut do co godzinę w ciągu pierwszych trzech dni. Następnie odbywają się codziennie dla każdej aktywnej domeny. Wystarczy opublikować rekordy i poczekać; większość domen weryfikuje się w ciągu kilku minut od propagacji DNS. Jeśli chcesz natychmiastowego sprawdzenia (np. zaraz po edycji DNS), wywołaj POST /v1/email/domains/{domain_id}/verify: uruchomi ono nowe sprawdzenie i zwróci zaktualizowaną domenę. Odpowiedź 200 z rekordami wciąż w stanie pending nie oznacza błędu; znaczy to, że rekordy nie zostały jeszcze znalezione, co jest normalne podczas propagacji DNS (minuty do godzin). Wywołanie można bezpiecznie powtarzać w trakcie oczekiwania.
Domena, która pozostaje niezweryfikowana przez około 14 dni, zostaje usunięta. Kilka dni przed usunięciem wysyłamy do obszaru roboczego przypomnienie e-mailem, abyś mógł dokończyć konfigurację.
Pole status na najwyższym poziomie domeny odzwierciedla własność, potwierdzoną rekordem DKIM:
- pending: rekord DKIM nie został jeszcze opublikowany.
- verified: rekord DKIM jest na miejscu; własność potwierdzona.
- failed: rekord DKIM istnieje, ale nie pasuje do oczekiwanej wartości, albo wcześniej zweryfikowany rekord został usunięty. Popraw rekord, aby odzyskać weryfikację.
- temporary_failure: rozwiązywanie DNS tymczasowo nie powiodło się; weryfikacja jest ponawiana automatycznie.
- rejected: domena została odrzucona ze względu na politykę; skontaktuj się ze wsparciem.
Gotowość do wysyłania jest raportowana osobno w capabilities. Bramka wysyłkowa to capabilities.sending, która przechodzi weryfikację tylko wtedy, gdy DKIM, CNAME return-path i polityka DMARC są na miejscu; SPF w apeksie domeny nie jest wymagany. Gotowość trackingu (capabilities.tracking) jest niezależna od bramki wysyłkowej: kontroluje, czy można używać brandowanego śledzenia otwarć i kliknięć, nigdy zaś tego, czy domena może wysyłać.
Gdy zweryfikowany rekord przestaje działać
Weryfikacja nigdy się nie kończy: codzienna ponowna kontrola pilnuje zweryfikowanych domen, więc jeśli Twój DNS później się zepsuje, zauważymy to. Aby uniknąć migotania przy przejściowych problemach DNS, zweryfikowany rekord, który zaczyna nie przechodzić ponownych kontroli, jest utrzymywany jako zweryfikowany w stanie ostrzegawczym i sprawdzany co godzinę, a my Cię powiadamiamy. Dopiero po 24 godzinach ciągłych niepowodzeń domena zostaje zdegradowana; każde pomyślne sprawdzenie w tym oknie kasuje ostrzeżenie. Degradacja obowiązuje od następnego wysłania, a zdegradowana domena ponownie weryfikuje się automatycznie po naprawieniu rekordów, przy następnej automatycznej kontroli lub ręcznej weryfikacji.
Zarządzanie domenami
Regiony. Stan domeny jest regionalny. Jeśli wysyłasz zarówno z us1, jak i eu1, zarejestruj domenę w każdym regionie; każda rejestracja otrzymuje własny selektor DKIM i weryfikuje się niezależnie.
Zmiana nazw hostów return-path lub trackingu. Te nazwy hostów należą do konfiguracji domeny w Twoim obszarze roboczym. Nazwa hosta, która już przeszła weryfikację, nigdy nie jest zastępowana niezweryfikowaną: zmiany są etapowane, weryfikowane równolegle z aktywną konfiguracją i promowane dopiero po pomyślnym sprawdzeniu nowych rekordów.
Śledzenie otwarć i kliknięć. Przełączniki settings należą do konfiguracji domeny w obszarze roboczym. Zmiany przełączników dotyczą wyłącznie tej konfiguracji domeny. Możesz je włączyć, gdy tylko domena trackingowa jest skonfigurowana. Włączenie przełącznika bez domeny trackingowej zwraca 409. Przełączniki wpływają na wysyłki dopiero po weryfikacji domeny trackingowej, więc weryfikacja jest egzekwowana przy każdym wysłaniu.
Usuwanie. DELETE /v1/email/domains/{domain_id} usuwa domenę wysyłkową z Twojego obszaru roboczego. Inne zastosowania domeny pozostają bez zmian.
Następne kroki
- DKIM, SPF i DMARC: co robi każdy rekord i jak dobierać wartości.
- Przewodniki DNS dla poszczególnych dostawców: instrukcje konfiguracji dla Cloudflare, Route 53, GoDaddy i innych.
- Dokumentacja API domen: pełne schematy żądań i odpowiedzi dla każdego endpointu.
Powiązane zasoby
Kontynuuj z dokumentacją, przewodnikami i przykładami dotyczącymi tego tematu. Zasoby są w języku angielskim.
Obejrzyj przewodnikGetting started with emailPoznaj możliwościEmailPodążaj ścieżką naukiBuild your first integrationPrzewodnik wdrożeniowySend your first email
Wypróbuj ćwiczenie i uzyskaj brief wdrożeniowy