Mittenti

Un workspace può avere un mittente per ogni tipo di invio, oltre al mittente generale. Così le email marketing, automatiche e transazionali partono da indirizzi e domini distinti, per esempio news@news.tuodominio.it per le campagne e ciao@tuodominio.it per le automazioni.

I tre tipi di invio

Ogni tipo è null (non configurato) oppure un oggetto con fromEmail, fromName e replyTo. fromEmail e fromName vanno insieme: un tipo è configurato oppure no, e non prende mai metà del mittente da quello generale.

Il mittente generale è la coppia defaultFromEmail / defaultFromName del workspace. Resta dov'era: non è stato copiato nei tre tipi, e un tipo che non hai mai configurato si comporta esattamente come prima.

Come si sceglie il mittente

Per ogni invio, Tratto prende il primo valore che esiste:

Un tipo non configurato eredita il mittente generale. Non è mai il motivo per cui un invio viene rifiutato.

Marketing

Una campagna creata senza fromEmail/fromName prende il mittente marketing, o quello generale se manca. Il mittente viene scritto sulla campagna al momento della creazione: cambiare il mittente marketing dopo non cambia le campagne già create. Vedi Campagne.

L'invio di prova di un template usa lo stesso mittente.

Automazioni

Quando attivi un flow, ogni step send_email senza un proprio from riceve il mittente automation, o quello generale se manca. Il mittente viene scritto sullo step all'attivazione e da lì resta quello, anche se poi cambi il mittente automation o quello generale. Disattivare e riattivare il flow non lo cambia, perché lo step ora ha un proprio from.

Per cambiare il mittente di un flow esistente: disattivalo, aggiorna i suoi step via API togliendo from, fromName e replyTo dallo step di invio, poi riattivalo. La dashboard oggi non permette di farlo: l'editor dei flow non ha il campo mittente. Vedi Flow.

Uno step che eredita il mittente automation eredita anche il suo replyTo. Uno step con un proprio from tiene il proprio indirizzo di risposta, o nessuno.

Transazionale

from è facoltativo su POST /v1/emails. Quando la richiesta non ha from, Tratto usa il mittente transazionale, o quello generale se manca. Una richiesta con from parte da quell'indirizzo, esattamente come prima: il mittente transazionale non lo sostituisce.

• Il mittente transazionale si usa con nome e indirizzo insieme.
• Il mittente generale si usa con il suo nome se defaultFromName è impostato, o come indirizzo nudo se c'è solo defaultFromEmail.
• Se mancano entrambi, la richiesta fallisce con 422 VALIDATION_ERROR e il messaggio No sender configured for this email., con un suggerimento che rimanda a Impostazioni → Mittenti.
• Con una chiave live, il dominio del mittente scelto deve essere verificato, come per un from esplicito: altrimenti 403 FORBIDDEN. Le chiavi test saltano questo controllo. Vedi Domini.

Il replyTo del mittente transazionale si applica solo quando la richiesta non ha né from né un proprio replyTo. Una richiesta con from non riceve alcun Reply-To dal mittente transazionale.

Negli SDK, omettere from richiede @tratto/email 1.5.0 o successiva, o tratto-email 2.0.0 o successiva (from_). Via HTTP si può omettere con qualsiasi client. Vedi Invia Email.

Regole

• fromEmail deve stare su un dominio verificato del workspace. Altrimenti l'aggiornamento fallisce con 403 FORBIDDEN e un messaggio che nomina il dominio, per esempio Domain 'news.tuodominio.it' is not verified for this tenant. Vedi Domini.
• replyTo non richiede un dominio verificato. Viene solo controllato che sia un indirizzo valido: uno malformato dà 422.
• fromName è lungo da 1 a 100 caratteri.
• Le email di sistema inviate da Tratto stesso, come gli inviti al team, non usano questi mittenti e non sono configurabili.

Leggere i mittenti

GET /v1/workspace restituisce senders con tutte e tre le chiavi, null dove un tipo non è configurato:

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

{
  "data": {
    "defaultFromEmail": "noreply@tuodominio.it",
    "defaultFromName": "La tua azienda",
    "senders": {
      "marketing": {
        "fromEmail": "news@news.tuodominio.it",
        "fromName": "Novità dalla tua azienda",
        "replyTo": "supporto@tuodominio.it"
      },
      "automation": null,
      "transactional": null
    }
  }
}

La risposta contiene altri campi del workspace: qui sono mostrati solo quelli del mittente.

Impostare o azzerare un mittente

PATCH /v1/workspace con senders aggiorna solo i tipi che invii. Gli altri mantengono il loro valore. null su un tipo lo azzera, e quel tipo torna al mittente generale. La chiave API deve avere il permesso workspace:write (vedi Autenticazione).

cURL

# Imposta il mittente marketing. automation e transactional restano invariati.
curl -X PATCH https://api.tratto.email/v1/workspace \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "senders": {
      "marketing": {
        "fromEmail": "news@news.tuodominio.it",
        "fromName": "Novità dalla tua azienda",
        "replyTo": "supporto@tuodominio.it"
      }
    }
  }'

# Azzeralo: marketing torna al mittente generale.
curl -X PATCH https://api.tratto.email/v1/workspace \
  -H "Authorization: Bearer tratto_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "senders": { "marketing": null } }'

Node.js (@tratto/email 1.2.0 o successiva)

import { Tratto } from '@tratto/email';

const tratto = new Tratto(process.env.TRATTO_API_KEY!);

await tratto.workspace.update({
  senders: {
    marketing: {
      fromEmail: 'news@news.tuodominio.it',
      fromName: 'Novità dalla tua azienda',
      replyTo: 'supporto@tuodominio.it',
    },
  },
});

await tratto.workspace.update({ senders: { marketing: null } });

Python (tratto-email 1.2.0 o successiva)

from tratto import Tratto

client = Tratto('tratto_live_...')

client.workspace.update({
    'senders': {
        'marketing': {
            'fromEmail': 'news@news.tuodominio.it',
            'fromName': 'Novità dalla tua azienda',
            'replyTo': 'supporto@tuodominio.it',
        }
    }
})

client.workspace.update({'senders': {'marketing': None}})

Nella dashboard

Apri Impostazioni → Mittenti. La prima riga è il mittente generale, poi una riga per tipo. Un tipo non configurato dice «Usa il mittente generale.». Ogni riga, compresa quella del generale, ha il suo nome, il suo indirizzo e il suo Salva: salvare il mittente generale non cambia i mittenti per tipo, e salvare un tipo non cambia il generale. Il mittente generale si può sostituire ma non togliere. Il selettore degli indirizzi propone solo i domini verificati del workspace; senza un dominio verificato il mittente generale è mostrato in sola lettura. I campi del mittente non sono più nella scheda Workspace.

La checklist di onboarding considera completato il passo del mittente appena il workspace ha un mittente qualsiasi, generale o di un tipo.