TrattoDocumentazione
HomeDocumentazioneBlog
ENIT
Inizia ora

Invia Email

L'endpoint principale per inviare email tramite Tratto

POST /v1/emails è l'endpoint principale per inviare email. Invia un'email transazionale semplice, usa un template, programma per dopo, o allega file.

Prerequisiti

Prima di poter inviare email, hai bisogno di un dominio di invio verificato. Vedi Domini per la configurazione.

Invio Minimo

Invia un'email di base con solo i campi obbligatori.

cURL

curl -X POST https://api.tratto.email/v1/emails \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Benvenuto!",
    "text": "Ciao, questa è un\'email di test."
  }'

Node.js

const response = await fetch('https://api.tratto.email/v1/emails', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer tratto_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    from: '[email protected]',
    to: '[email protected]',
    subject: 'Benvenuto!',
    text: 'Ciao, questa è un\'email di test.',
  }),
});
const { data } = await response.json();
console.log('Email inviata:', data.id);

Python

import requests

response = requests.post(
  'https://api.tratto.email/v1/emails',
  headers={
    'Authorization': 'Bearer tratto_live_...',
    'Content-Type': 'application/json',
  },
  json={
    'from': '[email protected]',
    'to': '[email protected]',
    'subject': 'Benvenuto!',
    'text': 'Ciao, questa è un\'email di test.',
  },
)
data = response.json()['data']
print(f"Email inviata: {data['id']}")

Risposta:

{
  "data": {
    "id": "email_abc123xyz",
    "status": "queued",
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Benvenuto!",
    "text": "Ciao, questa è un'email di test.",
    "createdAt": "2025-06-30T12:00:00Z"
  }
}

Invia con HTML

Includi sia text (fallback) che html (contenuto renderizzato):

curl -X POST https://api.tratto.email/v1/emails \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Benvenuto!",
    "text": "Ciao, questa è un\'email di test.",
    "html": "<h1>Ciao!</h1><p>Questa è un\'email di test.</p>"
  }'

I client email mostrano html se supportato; ricadere a text altrimenti.

A seconda del tuo piano, Tratto può aggiungere un footer alla versione HTML — il badge "Sent using Tratto", obbligatorio su alcuni piani (oggi Free) e facoltativo sugli altri. Vedi Footer Email & Branding.

Invia con Markdown

Passa un corpo markdown invece di html e Tratto lo renderizza lato server in HTML responsive ed email-safe (più una parte in testo semplice) usando il formato Markdown:

curl -X POST https://api.tratto.email/v1/emails \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Benvenuto!",
    "markdown": "# Benvenuto, {{firstName}}!\n\nGrazie per esserti registrato.\n\n[Apri la dashboard](https://app.tuodominio.it){button}",
    "variables": {"firstName": "Alice"}
  }'

Regole e comportamento:

  • markdown e html sono mutuamente esclusivi — inviarli entrambi fallisce con 422 ("markdown and html are mutually exclusive — provide one or the other.").
  • Almeno uno tra html, text, markdown o templateId è obbligatorio, e un markdown vuoto fallisce con 422 ("markdown must not be empty.").
  • Il markdown viene renderizzato una volta, alla richiesta; l'HTML e il testo risultanti vengono memorizzati sull'email, quindi i retry di consegna non ri-renderizzano mai.
  • Un campo text esplicito vince sulla parte testuale generata dal render.
  • Le {{variabili}} vengono sostituite alla consegna, dopo il render — come per ogni altro invio.
  • L'HTML raw dentro il markdown viene escapato a testo letterale, e i link javascript: / data: non diventano mai link. Vedi Template Markdown per la sintassi e il modello di sicurezza.

Invia con un Template

Invece di comporre HTML nel codice, usa un template con sostituzione di variabili.

Step 1: Crea un template (vedi Template)

{
  "name": "Email di Benvenuto",
  "html": "<h1>Ciao {{firstName}}!</h1><p>Il tuo codice: {{code}}</p>"
}

Un template contiene un nome e un corpo. Non ha un oggetto: quello appartiene al singolo invio.

Step 2: Invia usando il template

curl -X POST https://api.tratto.email/v1/emails \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Benvenuta, Alice!",
    "templateId": "tmpl_abc123",
    "variables": {
      "firstName": "Alice",
      "code": "SECRET123"
    }
  }'

subject è obbligatorio su ogni invio. L'oggetto e l'html del template (e, per un template Markdown, la sua parte testuale fissata) vengono renderizzati con le variables che passi; una variabile che non passi diventa una stringa vuota.

Programma un'Email

Invia un'email a un orario futuro usando il campo scheduledAt (formato ISO 8601):

curl -X POST https://api.tratto.email/v1/emails \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Promemoria!",
    "text": "Ci vediamo domani.",
    "scheduledAt": "2025-07-01T09:00:00Z"
  }'

L'email verrà messa in coda e inviata all'orario specificato (deve essere nel futuro).

Aggiungi Allegati

Includi file come allegati codificati in base64:

curl -X POST https://api.tratto.email/v1/emails \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Fattura",
    "text": "Vedi allegato fattura.",
    "attachments": [
      {
        "filename": "fattura.pdf",
        "contentType": "application/pdf",
        "content": "JVBERi0xLjQKJeLj..."
      }
    ]
  }'

Passaggi per allegare un file:

  1. Leggi il file come binario
  2. Codifica il contenuto in base64
  3. Includi filename, contentType, e content nell'array attachments

Esempio JavaScript:

const fs = require('fs');

const fileBuffer = fs.readFileSync('fattura.pdf');
const base64Content = fileBuffer.toString('base64');

const attachments = [
  {
    filename: 'fattura.pdf',
    contentType: 'application/pdf',
    content: base64Content,
  },
];

Tag per l'Organizzazione

Aggiungi tag per organizzare e filtrare le email:

curl -X POST https://api.tratto.email/v1/emails \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Conferma Ordine",
    "text": "Il tuo ordine è stato confermato.",
    "tags": ["ordine", "transazionale"]
  }'

Successivamente, filtra le email per tag o usali nei webhook.

Riferimento Completo del Request Body

CampoTipoObbligatorioDescrizione
fromstring✓Indirizzo email del mittente (deve essere da un dominio verificato)
tostring✓Indirizzo email del destinatario
ccstring[]Destinatari di copia carbone
bccstring[]Destinatari di copia carbone nascosta
subjectstring✓ (se non usi template)Riga di oggetto dell'email
textstringContenuto testo semplice (usato come fallback)
htmlstringContenuto HTML (mutuamente esclusivo con markdown)
markdownstringMarkdown, renderizzato lato server (mutuamente esclusivo con html, max 100.000 caratteri)
templateIdstringTemplate ID (al posto di subject/text/html)
variablesobjectVariabili da interpolate nel template
attachmentsarrayArray di oggetti allegati
scheduledAtstring (ISO 8601)Programma email per consegna futura
tagsstring[]Tag di organizzazione (max 10)
replyTostringIndirizzo di risposta
headersobjectCustom email headers (avanzato)

Risposta

Successo (2xx):

{
  "data": {
    "id": "email_abc123xyz",
    "status": "queued",
    "from": "[email protected]",
    "to": "[email protected]",
    "cc": [],
    "bcc": [],
    "subject": "Benvenuto!",
    "createdAt": "2025-06-30T12:00:00Z",
    "scheduledAt": null
  }
}

Errore (4xx):

{
  "error": {
    "code": "FORBIDDEN",
    "message": "The sending domain is not verified.",
    "docs": "https://docs.tratto.email/it/domains",
    "suggestion": "Add and verify the domain at https://app.tratto.email/domains before sending."
  }
}

Errori Comuni

FORBIDDEN: dominio non verificato

Causa: Il dominio from non è ancora verificato. L'API restituisce 403 con il dominio indicato in message.

Fix: Completa il processo di verifica del dominio.

RATE_LIMITED

Causa: Più di 100 richieste in un secondo con la stessa chiave API, o più di 500 richieste in un minuto dallo stesso IP.

Fix: Implementa backoff esponenziale e riprova più tardi. Vedi Rate Limits.

VALIDATION_ERROR

Causa: Richiesta non valida (campo mancante, JSON malformato, ecc.).

Fix: Controlla il messaggio di errore e consulta il riferimento Codici di Errore.

Prossimi Passi

Modifica questa pagina su GitHub

Ultimo aggiornamento

Autenticazione e API Key

Gestire le API key e autenticare le richieste

Template: Crea, Versiona e Test

Gestisci template email versionati con sostituzione di variabili

In questa pagina

Prerequisiti
Invio Minimo
Invia con HTML
Invia con Markdown
Invia con un Template
Programma un'Email
Aggiungi Allegati
Tag per l'Organizzazione
Riferimento Completo del Request Body
Risposta
Errori Comuni
FORBIDDEN: dominio non verificato
RATE_LIMITED
VALIDATION_ERROR
Prossimi Passi