Invia la Tua Prima Email

Invia la tua prima email in meno di tre minuti. Per iniziare non serve configurare il DNS: una API key di test fa girare l'intera pipeline (stati, timeline, webhook) senza consegnare email reali. Andare in produzione è l'ultimo passo, non il primo.

Step 1: Ottieni una API key di test

Il wizard di onboarding te ne propone una subito dopo la registrazione. Puoi anche crearla in qualsiasi momento dalla dashboard in Impostazioni → API key (scegli l'ambiente Test), oppure via API se hai già una chiave:

curl -X POST https://api.tratto.email/v1/api-keys \
  -H "Authorization: Bearer TUA_KEY_ESISTENTE" \
  -H "Content-Type: application/json" \
  -d '{"name":"quickstart","env":"test","permissions":["emails:send","emails:read"]}'

Le chiavi di test iniziano con tratto_test_, quelle live con tratto_live_.

La chiave viene mostrata una sola volta. Trattala come una password e non esporla mai client-side.

Step 2: Invia un'email

In modalità test va bene qualsiasi indirizzo from sintatticamente valido: non serve un dominio verificato.

cURL

curl -X POST https://api.tratto.email/v1/emails \
  -H "Authorization: Bearer tratto_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@tuodominio.it",
    "to": "delivered@simulator.tratto.email",
    "subject": "Ciao da Tratto!",
    "text": "Se vedi questo, funziona!"
  }'

Node.js

const response = await fetch('https://api.tratto.email/v1/emails', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer tratto_test_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: 'hello@tuodominio.it',
    to: 'delivered@simulator.tratto.email',
    subject: 'Ciao da Tratto!',
    text: 'Se vedi questo, funziona!',
  }),
});
const { data } = await response.json();
console.log('Email ID:', data.id); // email_...
console.log('Live mode:', data.livemode); // false

Python

import requests

response = requests.post(
  'https://api.tratto.email/v1/emails',
  headers={
    'Authorization': 'Bearer tratto_test_...',
    'Content-Type': 'application/json',
  },
  json={
    'from': 'hello@tuodominio.it',
    'to': 'delivered@simulator.tratto.email',
    'subject': 'Ciao da Tratto!',
    'text': 'Se vedi questo, funziona!',
  },
)
data = response.json()['data']
print(data['id'], data['livemode'])  # email_...  False

PHP

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

$email = $tratto->emails->send([
    'from' => 'hello@tuodominio.it',
    'to' => 'delivered@simulator.tratto.email',
    'subject' => 'Ciao da Tratto!',
    'text' => 'Se vedi questo, funziona!',
]);
echo $email['id'], ' ', var_export($email['livemode'], true); // email_...  false

Risposta:

{
  "data": {
    "id": "email_xyz789",
    "livemode": false
  }
}

Step 3: Seguila lungo la pipeline

In pochi secondi l'email passa da queued → sent → delivered, con gli eventi nella sua timeline, esattamente come il traffico di produzione:

curl https://api.tratto.email/v1/emails/email_xyz789 \
  -H "Authorization: Bearer tratto_test_..."

Alcuni indirizzi destinatario speciali simulano gli altri esiti:

Destinatario	Esito
`delivered@simulator.tratto.email` (o qualsiasi altro indirizzo)	`delivered`
`bounced@simulator.tratto.email`	bounce permanente: l'email finisce in `bounced`
`soft-bounced@simulator.tratto.email`	bounce temporaneo: anche questa finisce in `bounced`
`complained@simulator.tratto.email`	segnalazione di spam

Se hai registrato un webhook, ricevi anche lì questi eventi, con livemode: false nel payload. Vedi Modalità test per la semantica completa.

Vai in produzione: verifica il tuo dominio

Le email reali partono da un dominio di tua proprietà. Aggiungilo:

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

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

{
  "data": {
    "id": "dom_abc123",
    "domain": "tuodominio.it",
    "status": "pending",
    "records": [
      { "type": "CNAME", "host": "token1._domainkey.tuodominio.it", "value": "token1.dkim.amazonses.com", "purpose": "dkim" },
      { "type": "CNAME", "host": "token2._domainkey.tuodominio.it", "value": "token2.dkim.amazonses.com", "purpose": "dkim" },
      { "type": "CNAME", "host": "token3._domainkey.tuodominio.it", "value": "token3.dkim.amazonses.com", "purpose": "dkim" },
      { "type": "TXT", "host": "tuodominio.it", "value": "v=spf1 include:amazonses.com ~all", "purpose": "spf" },
      { "type": "TXT", "host": "_dmarc.tuodominio.it", "value": "v=DMARC1; p=quarantine; rua=mailto:dmarc@tuodominio.it", "purpose": "dmarc" },
      { "type": "TXT", "host": "_tratto.tuodominio.it", "value": "tratto-verify=4f1c9a0e...", "purpose": "ownership" }
    ]
  }
}

Aggiungi presso il tuo provider DNS tutti i record della risposta. I tre record CNAME DKIM e il record TXT di proprietà _tratto sono obbligatori per la verifica; SPF e DMARC sono fortemente consigliati per la deliverability.

Se il tuo dominio ha già un record SPF (da Cloudflare Email Routing, Google Workspace, Microsoft 365 e simili), aggiungi include:amazonses.com a quello invece di crearne un secondo, per esempio v=spf1 include:amazonses.com include:_spf.mx.cloudflare.net ~all. Un dominio deve avere esattamente un record v=spf1: due rompono SPF per ogni mittente.

Amazon SES segnala che la propagazione delle modifiche DNS può richiedere fino a 72 ore. La verifica gira anche in automatico: Tratto ricontrolla i domini in attesa ogni 10 minuti.

Verifica quando sei pronto:

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

Quando status è verified, sostituisci la chiave di test con una live (tratto_live_...): stesso codice, consegna reale. È l'unica modifica.

Prossimi Passi

Tutto sulle chiavi di test? Vedi Modalità test
Inviare con i template? Vedi Template
Tracciare aperture e clic? Configura i Webhook
Capire tutti i campi? Leggi Invia Email
Usare un SDK? Prova l'SDK Node.js, l'SDK Python o l'SDK PHP

Bloccato? Consulta i Codici di Errore o Autenticazione.