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.

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']}")

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:[email protected]", "verified": false, "purpose": "dmarc" }
    ],
    "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.

Configurazione Record DNS

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

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. Sono gli unici record che Tratto controlla: devono risolversi tutti e tre prima che il dominio diventi verified.

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:[email protected]

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 al tuo dominio.

Verifica

Tratto verifica solo DKIM, chiedendo ad Amazon SES se ha trovato i tre record CNAME. 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 il dominio è verified.

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

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']}")

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 predefinito: quando un dominio diventa verified per la prima volta e il workspace non ha un mittente predefinito, Tratto lo imposta a noreply@ su quel dominio.

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 non corrisponde.

Fix:

1. Confronta host e valore di ogni record DKIM 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 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.

SPF vs DKIM vs DMARC

Best practice: Pubblica tutti e cinque 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.

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