Invia un’email

Questa guida spiega ogni parte di una richiesta POST /emails e cosa ne fa Emailit, dall’indirizzo From agli errori che puoi ricevere. Per il riferimento completo dei parametri, vedi Invia un’email nel riferimento API.

Prima di iniziare

• Un dominio di invio verificato nel workspace. Vedi Aggiungi un dominio.
• Una chiave API con permesso Full Access o Sending Only. Vedi Chiavi API.
• L’accesso alla produzione, se invii a persone che non sono membri del workspace. Vedi Accesso alla produzione.
• Crediti sufficienti per tutti i destinatari (1 credito ciascuno).

Invia un’email di base

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com", "Grace Hopper <grace@example.com>"],
    "cc": "accounts@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your invoice for October",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready."
  }'

import { Emailit } from '@emailit/node';

const emailit = new Emailit(process.env.EMAILIT_API_KEY);

const email = await emailit.emails.send({
  from: 'Acme Billing <billing@acme.com>',
  to: ['ada@example.com', 'Grace Hopper <grace@example.com>'],
  cc: 'accounts@example.com',
  reply_to: 'support@acme.com',
  subject: 'Your invoice for October',
  html: '<p>Your invoice is ready.</p>',
  text: 'Your invoice is ready.',
});

import os
from emailit import EmailitClient

client = EmailitClient(os.environ["EMAILIT_API_KEY"])

email = client.emails.send({
    "from": "Acme Billing <billing@acme.com>",
    "to": ["ada@example.com", "Grace Hopper <grace@example.com>"],
    "cc": "accounts@example.com",
    "reply_to": "support@acme.com",
    "subject": "Your invoice for October",
    "html": "<p>Your invoice is ready.</p>",
    "text": "Your invoice is ready.",
})

$emailit = Emailit::client(getenv('EMAILIT_API_KEY'));

$email = $emailit->emails()->send([
    'from' => 'Acme Billing <billing@acme.com>',
    'to' => ['ada@example.com', 'Grace Hopper <grace@example.com>'],
    'cc' => 'accounts@example.com',
    'reply_to' => 'support@acme.com',
    'subject' => 'Your invoice for October',
    'html' => '<p>Your invoice is ready.</p>',
    'text' => 'Your invoice is ready.',
]);

Imposta l’indirizzo From

from è obbligatorio e accetta un indirizzo in una di queste forme:

• billing@acme.com
• Acme Billing <billing@acme.com>, oppure con le virgolette, "Acme, Inc." <billing@acme.com>

Il dominio dopo la @ deve essere un dominio di invio verificato nello stesso workspace:

• La corrispondenza è esatta. I domini vengono confrontati senza distinzione tra maiuscole e minuscole, ma mail.acme.com e acme.com sono domini diversi. Aggiungi e verifica ogni sottodominio da cui invii.
• Va bene qualsiasi parte locale. Non ti serve una casella per billing@ o no-reply@.
• I domini in attesa non possono inviare. Un dominio ancora in attesa di revisione (Pending verification) viene trattato come non verificato.
• Le chiavi limitate restano sul loro dominio. Una chiave Sending Only limitata a un dominio può inviare solo da quel dominio.
• I domini in pausa sono bloccati. Se la salute degli invii ha messo in pausa il dominio, gli invii da quel dominio vengono rifiutati finché la pausa non viene rimossa.

Aggiungi i destinatari

to è obbligatorio. cc e bcc sono facoltativi. Ogni campo accetta una stringa o un array di stringhe, con o senza nomi visualizzati, e contiene fino a 50 indirizzi. Una stringa può contenere più indirizzi separati da virgole; usa un array quando un nome visualizzato contiene a sua volta una virgola.

Emailit rimuove i duplicati tra to, cc e bcc (senza distinzione tra maiuscole e minuscole), poi crea un’email per ogni destinatario unico, ciascuna con il proprio ID em_. Ogni copia ha gli stessi header To e Cc, così i destinatari vedono la conversazione come al solito, e i destinatari in Bcc non compaiono mai negli header di nessuna copia.

Quando una richiesta ha più di un destinatario, la risposta include una mappa ids dal destinatario all’ID dell’email. id è l’email del primo destinatario.

{
  "object": "email",
  "id": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
  "ids": {
    "ada@example.com": "em_33VtK8mRq1xZp7LwN4cY2bHsDfa",
    "grace@example.com": "em_33VtK8nB5rTq0YxW3mJk9PdLsUe",
    "accounts@example.com": "em_33VtK8nQ2wErT6yU8iOp4AsDf7g"
  }
}

Ogni destinatario costa 1 credito e rientra nei limiti di frequenza. Un destinatario con una soppressione di tipo recipient viene accettato e poi segnato come suppressed invece di essere consegnato.

Scrivi il contenuto

Se reply_to indica lo stesso indirizzo di from, Emailit rimuove l’header Reply-To, perché non aggiunge nulla e alcuni filtri antispam lo penalizzano.

Invia con un template

Imposta template sull’alias di un template o su un ID tem_, e passa variables per i segnaposto Temple che contiene.

• Un alias invia la versione attualmente pubblicata per quell’alias. Se nessuna versione è pubblicata, la richiesta non riesce con 404.
• Un ID tem_ invia esattamente quella versione, pubblicata o no. Usalo per testare una versione in bozza prima di pubblicarla.

I campi della richiesta hanno la precedenza sul template: un subject, html o text che invii sostituisce il valore del template. Se non invii reply_to, viene usato il Reply-To del template. from è sempre obbligatorio nella richiesta. Vedi Versioni dei template per come funziona la pubblicazione.

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "template": "welcome-email",
    "variables": {
      "first_name": "Ada",
      "plan": "Pro",
      "activation_url": "https://acme.com/activate?token=8f3k2"
    }
  }'

const email = await emailit.emails.send({
  from: 'Acme <hello@acme.com>',
  to: 'ada@example.com',
  template: 'welcome-email',
  variables: {
    first_name: 'Ada',
    plan: 'Pro',
    activation_url: 'https://acme.com/activate?token=8f3k2',
  },
});

email = client.emails.send({
    "from": "Acme <hello@acme.com>",
    "to": "ada@example.com",
    "template": "welcome-email",
    "variables": {
        "first_name": "Ada",
        "plan": "Pro",
        "activation_url": "https://acme.com/activate?token=8f3k2",
    },
})

$email = $emailit->emails()->send([
    'from' => 'Acme <hello@acme.com>',
    'to' => 'ada@example.com',
    'template' => 'welcome-email',
    'variables' => [
        'first_name' => 'Ada',
        'plan' => 'Pro',
        'activation_url' => 'https://acme.com/activate?token=8f3k2',
    ],
]);

variables funziona anche senza template: Emailit elabora i segnaposto Temple nei campi subject, html e text che invii direttamente.

Controlla il tracciamento

Per impostazione predefinita, ogni email segue le impostazioni Track loads e Track clicks del suo dominio di invio. Puoi sovrascriverle per singola email con tracking:

• "tracking": true o false attiva o disattiva sia il tracciamento dei caricamenti (aperture) sia quello dei clic.
• "tracking": { "loads": true, "clicks": false } li imposta separatamente.

Il tracciamento funziona solo quando il CNAME di tracciamento del dominio è verificato. Senza, l’email viene inviata senza tracciamento e la richiesta riesce comunque. L’oggetto tracking nella risposta mostra le impostazioni effettivamente applicate. Vedi Tracciamento di aperture e clic.

Aggiungi header e metadati

Usa headers per gli header email personalizzati, come List-Unsubscribe, e meta per le tue coppie chiave-valore di tipo stringa. Emailit salva meta con l’email e lo include negli eventi webhook. Vedi Header e metadati.

Per allegare file, programmare l’invio o rendere sicuri i nuovi tentativi, vedi Allegati, Programmazione e Idempotenza.

Leggi la risposta

Una richiesta riuscita restituisce 200:

Salva l’id (o la mappa ids) per poter associare gli eventi webhook successivi e recuperare l’email con Recupera un’email.

Eventi

L’email di ogni destinatario genera i propri eventi:

1. email.accepted subito dopo la richiesta, oppure email.scheduled se ha un orario di invio futuro.
2. Gli eventi di consegna man mano che l’email attraversa la pipeline: email.delivered, email.attempted (errore temporaneo, verrà ritentata), email.bounced, email.failed, email.rejected o email.suppressed. Un’email trattenuta per revisione genera email.held.
3. Gli eventi di engagement, se il tracciamento è attivo: email.loaded ed email.clicked. Le segnalazioni di spam generano email.complained.

Vedi Stati delle email per il significato di ogni stato.

Errori

Gli errori di convalida restituiscono l’elenco di tutti i problemi trovati:

{
  "error": "Validation failed",
  "validation_errors": [
    "Missing required field: subject",
    "Invalid to email address at index 1: grace@"
  ]
}

Un workspace sospeso riceve 403 con Workspace is suspended a ogni invio. Per il formato generale degli errori, vedi Errori.

Vedi anche

• Invia un’email nel riferimento API
• Template
• Stati delle email
• Tipi di evento
• Perché la mia email non è arrivata?