Domini: Aggiungi, Configurazione DNS e Verifica

Un dominio è la tua identità di invio verificata. Prima di inviare email reali, devi aggiungere un dominio e pubblicare i record DNS che Tratto restituisce.

Perché i Domini Contano

• Autenticazione Mittente: Prova che controlli il dominio
• Deliverability: SPF, DKIM, DMARC prevengono spoofing e migliorano il posizionamento in inbox
• Fiducia: I destinatari vedono il tuo dominio branded, non un servizio di terze parti

Aggiungi un Dominio

Registra il tuo dominio con Tratto. Il numero di domini ha un tetto per piano ed è contato su tutti i workspace dell'account, compresi i domini ancora pending e quelli failed: oltre il tetto la richiesta fallisce con 429 QUOTA_EXCEEDED. Vedi Limiti di Piano.

Nella dashboard solo il proprietario del workspace aggiunge, verifica e rimuove i domini: un membro può leggerli, e riceve 403 FORBIDDEN (Only the workspace owner can do this.) sul resto. Vedi Team.

cURL

curl -X POST https://api.tratto.email/v1/domains \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{"domain":"hello.tuodominio.it"}'

Node.js

const response = await fetch('https://api.tratto.email/v1/domains', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer tratto_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ domain: 'hello.tuodominio.it' }),
});
const { data } = await response.json();
console.log('Domain ID:', data.id);

Python

import requests

response = requests.post(
  'https://api.tratto.email/v1/domains',
  headers={
    'Authorization': 'Bearer tratto_live_...',
    'Content-Type': 'application/json',
  },
  json={'domain': 'hello.tuodominio.it'},
)
data = response.json()['data']
print(f"Domain ID: {data['id']}")

PHP

$tratto = new \Tratto\Client(getenv('TRATTO_API_KEY'));

$domain = $tratto->domains->add('hello.tuodominio.it');
echo "Domain ID: {$domain['id']}\n";

Risposta (201; i valori sono esempi, usa sempre quelli della tua risposta):

{
  "data": {
    "id": "dom_abc123",
    "domain": "hello.tuodominio.it",
    "status": "pending",
    "records": [
      { "type": "CNAME", "host": "token1._domainkey.hello.tuodominio.it", "value": "token1.dkim.amazonses.com", "verified": false, "purpose": "dkim" },
      { "type": "CNAME", "host": "token2._domainkey.hello.tuodominio.it", "value": "token2.dkim.amazonses.com", "verified": false, "purpose": "dkim" },
      { "type": "CNAME", "host": "token3._domainkey.hello.tuodominio.it", "value": "token3.dkim.amazonses.com", "verified": false, "purpose": "dkim" },
      { "type": "TXT", "host": "hello.tuodominio.it", "value": "v=spf1 include:amazonses.com ~all", "verified": false, "purpose": "spf" },
      { "type": "TXT", "host": "_dmarc.hello.tuodominio.it", "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@hello.tuodominio.it", "verified": false, "purpose": "dmarc" },
      { "type": "TXT", "host": "_tratto.hello.tuodominio.it", "value": "tratto-verify=4f1c9a0e...", "verified": false, "purpose": "ownership" }
    ],
    "createdAt": "2026-06-30T12:00:00.000Z",
    "updatedAt": "2026-06-30T12:00:00.000Z",
    "verifiedAt": null
  }
}

Lo status del dominio è pending: Tratto attende che Amazon SES, che consegna le tue email, trovi i record DKIM, e che il record di proprietà sia pubblicato.

Configurazione Record DNS

Aggiungi i record di records presso il tuo provider DNS (GoDaddy, Namecheap, Cloudflare, Route 53, ecc.). Ogni dominio ne riceve sei:

1. Record DKIM (obbligatori)

Tipo: CNAME, tre record
Host: <token>._domainkey.hello.tuodominio.it
Valore: <token>.dkim.amazonses.com

I tre token sono unici per il tuo dominio: copia host e valore di ciascuno dalla tua risposta. Amazon SES genera e gestisce la chiave di firma, e i record CNAME puntano alle sue chiavi pubbliche. Devono risolversi tutti e tre prima che il dominio diventi verified, insieme al record di proprietà.

2. Record SPF (consigliato)

Tipo: TXT
Host: hello.tuodominio.it
Valore: v=spf1 include:amazonses.com ~all

Questo autorizza Amazon SES a inviare per l'hostname.

3. Record DMARC (consigliato)

Tipo: TXT
Host: _dmarc.hello.tuodominio.it
Valore: v=DMARC1; p=quarantine; rua=mailto:dmarc@hello.tuodominio.it

Questo chiede ai server riceventi di mettere in quarantena la posta che non supera l'autenticazione. La policy vale per tutta la posta inviata a nome del dominio, non solo per quella inviata tramite Tratto: assicurati che gli altri servizi che inviano per il dominio siano autenticati prima di pubblicarla. Tieni un solo record DMARC per host. Tratto non controlla questo record, quindi puoi adattare la policy e l'indirizzo rua. Se non sei sicuro che tutti gli altri servizi che inviano a nome del dominio siano autenticati, parti con p=none, che chiede solo i report, leggili per qualche settimana e poi passa a p=quarantine.

L'indirizzo rua suggerito è una casella sul dominio stesso, perché i report aggregati elencano IP e volumi di tutte le fonti che inviano a nome del tuo dominio, Tratto o no, e quei dati sono tuoi. Un rua su un altro dominio funziona solo se quel dominio pubblica un record di autorizzazione per il tuo (RFC 7489, sezione 7.1); senza, i server riceventi scartano i report. Tratto non controlla che la casella esista, e non riceve né legge i tuoi report: creala, oppure fai puntare rua a un indirizzo dello stesso dominio che leggi già.

4. Record di proprietà (obbligatorio)

Tipo: TXT
Host: _tratto.hello.tuodominio.it
Valore: tratto-verify=<token>

Questo record dimostra che il tuo workspace controlla il DNS del dominio. I record DKIM da soli non bastano: un dominio rimosso da un workspace e aggiunto in un altro verrebbe altrimenti verificato dai record lasciati dal proprietario precedente. Il token appartiene al tuo workspace e a questo dominio esatto, quindi un record pubblicato per un altro workspace non corrisponde mai.

• Copia il valore dal record con purpose: "ownership" in records, restituito da POST /v1/domains e da GET /v1/domains/{id}.
• Il token resta lo stesso se rimuovi il dominio e lo aggiungi di nuovo nello stesso workspace.
• Un sottodominio e il dominio padre sono due domini: hello.tuodominio.it e tuodominio.it nello stesso workspace richiedono due record TXT, _tratto.hello.tuodominio.it e _tratto.tuodominio.it, con token diversi.
• Un dominio già verified non ne ha bisogno: Tratto controlla il record solo quando un dominio passa a verified.

Verifica

Tratto controlla due cose: chiede ad Amazon SES se ha trovato i tre record CNAME DKIM, poi cerca da sé il record TXT di proprietà. Il dominio diventa verified solo quando li trova entrambi. SPF e DMARC non vengono mai controllati: il loro flag verified è sempre false, anche su un dominio verificato. I tre record DKIM condividono un unico flag, che diventa true quando Amazon SES li ha trovati. Il record di proprietà ha un flag suo, che diventa true quando Tratto trova il record TXT. Tratto cerca il record TXT solo dopo che i record DKIM sono stati trovati, quindi finché DKIM è in attesa il flag di proprietà resta false, anche se il record TXT è già pubblicato.

Il controllo avviene in due modi:

• In automatico: un job in background ricontrolla ogni 10 minuti tutti i domini pending
• Su richiesta: POST /v1/domains/{id}/verify controlla subito

Se il record di proprietà è stato cercato prima che tu lo pubblicassi, un resolver DNS può ricordarne l'assenza per tutto il TTL di cache negativa della tua zona (RFC 2308): il dominio può restare pending per quel tempo dopo la pubblicazione. Se la ricerca stessa non riesce (timeout DNS o errore del server), lo status resta quello che era e il controllo successivo riprova.

Verifica Subito

cURL

curl -X POST https://api.tratto.email/v1/domains/dom_abc123/verify \
  -H "Authorization: Bearer tratto_live_..."

Node.js

const response = await fetch('https://api.tratto.email/v1/domains/dom_abc123/verify', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer tratto_live_...' },
});
const { data } = await response.json();
console.log('Status:', data.status);

Python

import requests

response = requests.post(
  'https://api.tratto.email/v1/domains/dom_abc123/verify',
  headers={'Authorization': 'Bearer tratto_live_...'},
)
data = response.json()['data']
print(f"Status: {data['status']}")

PHP

$tratto = new \Tratto\Client(getenv('TRATTO_API_KEY'));

$domain = $tratto->domains->verify('dom_abc123');
echo "Status: {$domain['status']}\n";

La risposta è il dominio completo, records inclusi, con 200 qualunque sia l'esito: leggi status, non il codice HTTP.

Cosa Sblocca verified

• Invii reali: un'email inviata con una chiave live (tratto_live_...) viene accettata solo se il dominio del from è verificato nel tuo workspace. Altrimenti l'API risponde 403 con FORBIDDEN.
• Corrispondenza esatta: il controllo confronta il dominio completo dopo la @. Verificare tuodominio.it non copre hello.tuodominio.it: aggiungi e verifica ogni dominio da cui invii.
• Invii di test: le chiavi di test (tratto_test_...) saltano questo controllo. Vedi Test mode.
• Mittente generale: quando un dominio diventa verified per la prima volta e il workspace non ha un mittente generale (defaultFromEmail), Tratto lo imposta a noreply@ su quel dominio. I mittenti per tipo (marketing, automation, transactional) non vengono impostati in automatico: vedi Mittenti.

Dopo la verifica

Il controllo automatico guarda solo i domini pending. Una volta che un dominio è verified, nessuno lo ricontrolla a intervalli regolari:

• Se in seguito togli o modifichi un CNAME DKIM o il record TXT di proprietà, il dominio resta verified in Tratto. Tieni tutti i record al loro posto finché invii da quel dominio.
• POST /v1/domains/{id}/verify su un dominio verificato chiede di nuovo ad Amazon SES lo stato attuale del DKIM. Se SES non trova più i record DKIM, il dominio torna pending o failed, e le email live da quel dominio vengono rifiutate finché non è di nuovo verificato. Il record di proprietà non viene ricontrollato finché il dominio resta verified.
• SPF e DMARC non vengono controllati, né prima né dopo la verifica.

Controlla lo Status del Dominio

Ottieni un dominio con i suoi record DNS.

cURL

curl https://api.tratto.email/v1/domains/dom_abc123 \
  -H "Authorization: Bearer tratto_live_..."

Risposta:

{
  "data": {
    "id": "dom_abc123",
    "domain": "hello.tuodominio.it",
    "status": "verified",
    "records": [ ... ],
    "createdAt": "2026-06-30T12:00:00.000Z",
    "updatedAt": "2026-06-30T12:10:00.000Z",
    "verifiedAt": "2026-06-30T12:10:00.000Z"
  }
}

Elenca i Domini

Ottieni tutti i domini per il tuo tenant. Ogni elemento ha id, domain, status e i timestamp, ma non records: per vederli richiedi il singolo dominio. Pagina con limit (da 1 a 100, default 50) e after.

cURL

curl https://api.tratto.email/v1/domains \
  -H "Authorization: Bearer tratto_live_..."

Rimuovi un Dominio

Elimina un dominio. Viene eliminata anche la sua identità in Amazon SES.

cURL

curl -X DELETE https://api.tratto.email/v1/domains/dom_abc123 \
  -H "Authorization: Bearer tratto_live_..."

Risoluzione dei Problemi DNS

Ancora pending dopo l'aggiunta dei record

Causa: il DNS non si è ancora propagato, oppure un record DKIM o di proprietà non corrisponde.

Fix:

1. Confronta host e valore di ogni record DKIM e di quello di proprietà con records di GET /v1/domains/{id}
2. Controlla che il provider non abbia aggiunto il dominio all'host una seconda volta
3. Usa MXToolbox o dig CNAME <token1>._domainkey.hello.tuodominio.it e dig TXT _tratto.hello.tuodominio.it per verificare che i record siano live
4. Attendi il prossimo controllo automatico (ogni 10 minuti), oppure chiama POST /v1/domains/{id}/verify

SPF e DMARC non influiscono sullo status: un record SPF o DMARC mancante non lascia mai un dominio in pending.

Dominio failed

Causa: Amazon SES ha smesso di cercare, di solito perché non ha trovato i record DKIM.

Fix: correggi i record DKIM, poi chiama POST /v1/domains/{id}/verify, che legge lo status attuale da Amazon SES. Se il dominio resta failed, rimuovilo, aggiungilo di nuovo e pubblica i record della nuova risposta.

Quali Record Controlla Tratto

Best practice: Pubblica tutti e sei i record per la massima deliverability.

Invio da Sottodominio

Puoi usare i sottodomini per inviare (es., hello.tuodominio.it) mentre il tuo dominio principale rimane pulito. Tratto confronta il dominio del from in modo esatto, quindi aggiungi e verifica il sottodominio stesso, con il suo record di proprietà.

Vantaggi:

• Isola la reputazione email dal dominio principale
• Test nuovi domini senza influenzare la produzione
• Separa l'infrastruttura di invio e ricezione

Prossimi Passi

• Inviare la tua prima email? Vai a Invia Email
• Testare la configurazione del dominio? Usa Quickstart
• Hai bisogno di aiuto con DNS? Vedi Deliverability per le best practice