Domini di invio
Prima che possiamo recapitare email dal tuo dominio, devi dimostrare di esserne il proprietario e pubblicare i record DNS che permettono ai provider di posta di autenticare i tuoi messaggi. Un dominio di invio è la risorsa con ambito spazio di lavoro (dom_...) che tiene traccia di questa configurazione: quali record pubblicare, cosa è stato verificato e se il dominio è pronto per l'invio.
Condividere un dominio tra organizzazioni
Lo stesso dominio può essere registrato da più organizzazioni senza interferenze reciproche. Ogni organizzazione dimostra la proprietà con la propria chiave DKIM, quindi:
- Un'altra organizzazione sullo stesso dominio non può mai vedere il tuo stato di verifica né modificare la tua configurazione.
- Ogni regione (us1, eu1) è indipendente: lo stesso dominio in due regioni corrisponde a due registrazioni separate con i propri record DNS. Registralo in ogni regione da cui invii.
Registrare un dominio
Crea il dominio con POST /v1/email/domains. La chiamata ha ambito spazio di lavoro e accetta il dominio di invio più etichette opzionali per gli hostname di return-path e tracking. Passa solo l'etichetta (send, links) e componiamo l'hostname completo sotto il tuo dominio di invio. I valori omessi assumono i default send e links.
Usa un sottodominio dedicato (mail.acme.com) anziché il tuo dominio registrato. Mantiene la reputazione di invio separata da tutto il resto del dominio e tiene ogni record che ti chiediamo di pubblicare lontano dall'apex della tua zona. La seconda ragione è quella che crea problemi: il record MX per la ricezione si trova sullo stesso nome dei record MX che già trasportano la posta aziendale, quindi su un dominio di invio apex pubblicarlo reindirizza quella posta verso di noi.
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" }
}'La risposta include status: pending, il selettore DKIM assegnato alla tua organizzazione, e i dns_records da pubblicare. Una registrazione già esistente nello spazio di lavoro restituisce 409. Il superamento della quota di domini della tua organizzazione restituisce 422. Sostituisci eu1 con us1 per uno spazio di lavoro US. Le chiavi API usano gli stessi prefissi regionali: bk_eu1_... e bk_us1_.... Puoi gestire i domini anche da Email > Domains.
Pubblicare i record DNS
L'array dns_records fornisce name, host e value pronti da copiare e incollare per ogni record. Alcuni provider rifiutano un valore TXT DKIM lungo come stringa singola; il DNS record splitter lo spezza nelle stringhe tra virgolette che quei provider si aspettano. Cosa pubblicare:
| Record | Tipo | Necessario per l'invio | Funzione |
|---|---|---|---|
| DKIM | TXT | Sì | Dimostra la proprietà e firma la tua posta con la chiave della tua organizzazione |
| Return-path CNAME | CNAME | Sì | Instrada i bounce verso di noi e copre SPF; la lookup SPF segue il CNAME, quindi non è necessario un record SPF sull'apex del tuo dominio |
| DMARC | TXT | Sì | Qualsiasi policy v=DMARC1 valida che copra il dominio di invio, sul dominio stesso o sul suo dominio registrato (organizzativo). Una policy p=none minimale è sufficiente. |
| Tracking CNAME | CNAME | No | Abilita hostname di tracking brandizzati per aperture/clic; i link tracciati vengono serviti tramite HTTPS una volta verificato |
| MX in entrata | MX | No | Instrada la posta per il dominio verso di noi per la ricezione. Riporta optional: true finché non abiliti la ricezione; pubblicarlo sostituisce i record MX che il dominio usa attualmente. |
Per lo scopo e i valori di ogni record, consulta DKIM, SPF e DMARC. I record MX per la ricezione sono in dns_records con purpose: inbound_mx quando la ricezione è disponibile nella tua regione, e riportano optional: true finché non abiliti la ricezione sul dominio. Salta ogni record contrassegnato come optional a meno che tu non voglia ciò che abilita. Per istruzioni di configurazione specifiche per provider DNS, consulta le guide Cloudflare, Route 53 o registrar generico.
La dashboard rileva i provider DNS supportati dai nameserver del tuo dominio e collega alle loro impostazioni DNS. Apri Email > Domains, poi seleziona un dominio per visualizzarne i record. Se qualcun altro gestisce il tuo DNS, POST /v1/email/domains/{domain_id}/dns-records/share gli invia un'email con i record da pubblicare.
Ciclo di vita della verifica
Un nuovo dominio inizia come pending. Non devi mai fare polling perché controlliamo i tuoi record automaticamente. I controlli iniziano immediatamente alla registrazione e rallentano da ogni paio di minuti a ogni ora nell'arco dei primi tre giorni. Poi vengono eseguiti quotidianamente per ogni dominio attivo. Pubblicare i record e attendere è sufficiente; la maggior parte dei domini viene verificata entro pochi minuti dalla propagazione DNS. Se vuoi un controllo immediato (ad esempio subito dopo aver modificato il DNS), chiama POST /v1/email/domains/{domain_id}/verify: esegue un controllo aggiornato e restituisce il dominio aggiornato. Una risposta 200 con record ancora pending non è un errore; significa che i record non sono stati ancora trovati, il che è normale durante la propagazione DNS (da minuti a ore). La chiamata può essere ripetuta in sicurezza mentre aspetti.
Un dominio che rimane non verificato per circa 14 giorni viene rimosso. Inviamo un'email di promemoria allo spazio di lavoro qualche giorno prima della rimozione perché tu possa completare la configurazione.
Il campo status di primo livello del dominio riflette la proprietà, dimostrata dal record DKIM:
- pending: il record DKIM non è stato ancora pubblicato.
- verified: il record DKIM è presente; la proprietà è confermata.
- failed: esiste un record DKIM ma non corrisponde al valore atteso, oppure un record precedentemente verificato è stato rimosso. Correggi il record per ripristinare la verifica.
- temporary_failure: la risoluzione DNS è fallita in modo transitorio; la verifica viene riprovata automaticamente.
- rejected: il dominio è stato rifiutato per motivi di policy; contatta il supporto.
La prontezza per l'invio è riportata separatamente sotto capabilities. Il gate di invio è capabilities.sending, che viene verificato solo quando DKIM, il CNAME return-path e una policy DMARC sono tutti presenti; SPF sull'apex del dominio non è richiesto. La prontezza del tracking (capabilities.tracking) è indipendente dal gate di invio: controlla se il tracking brandizzato di aperture/clic può essere usato, mai se il dominio può inviare.
Quando un record verificato si interrompe
La verifica non si ferma mai: il ricontrollo quotidiano tiene sotto controllo i domini verificati, quindi se il tuo DNS si guasta in seguito, ce ne accorgiamo. Per evitare oscillazioni su anomalie DNS transitorie, un record verificato che inizia a fallire i ricontrolli viene mantenuto verificato in stato di avviso e ricontrollato ogni ora, e ti avvisiamo. Solo dopo che il record ha continuato a fallire per 24 ore intere il dominio viene declassato; qualsiasi controllo positivo all'interno di quella finestra annulla l'avviso. I declassamenti hanno effetto sull'invio successivo, e un dominio declassato si ri-verifica automaticamente una volta corretti i record, al prossimo controllo automatico o a una verifica manuale.
Gestire i domini
Regioni. Lo stato del dominio è regionale. Se invii sia da us1 che da eu1, registra il dominio in ogni regione; ogni registrazione ottiene il proprio selettore DKIM e viene verificata indipendentemente.
Modifica degli hostname di return-path o tracking. Questi hostname appartengono alla configurazione del dominio del tuo spazio di lavoro. Un hostname già verificato non viene mai sostituito da uno non verificato: le modifiche vengono messe in attesa, verificate insieme alla tua configurazione attiva e promosse solo quando i nuovi record superano il controllo.
Tracking di aperture/clic. I toggle settings appartengono alla configurazione del dominio dello spazio di lavoro. Le modifiche ai toggle si applicano solo a questa configurazione del dominio. Puoi attivarli non appena un dominio di tracking è configurato. Abilitarne uno senza un dominio di tracking restituisce un 409. I toggle hanno effetto sugli invii solo dopo che quel dominio di tracking è verificato, quindi la verifica è applicata per ogni invio.
Eliminazione. DELETE /v1/email/domains/{domain_id} rimuove il dominio di invio dal tuo spazio di lavoro. Gli altri usi del dominio restano invariati.
Prossimi passi
- DKIM, SPF e DMARC: cosa fa ogni record e come scegliere i valori.
- Guide DNS per provider: istruzioni di configurazione per Cloudflare, Route 53, GoDaddy e altri.
- Riferimento API dei domini: schemi completi di request/response per ogni endpoint.
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.
Guarda la guidaGetting started with emailEsplora la funzionalitàEmailSegui il percorso di apprendimentoBuild your first integrationGuida all'implementazioneSend your first email
Prova l'esercitazione e ottieni un brief di implementazione