Migra da SendGrid

Questa guida fa corrispondere concetti, chiamate API, webhook, soppressioni e template di SendGrid ai loro equivalenti in Emailit. Leggi prima Passa a Emailit per l’ordine generale e per sapere come usare entrambi i provider in parallelo.

Concetti

Aggiorna le chiamate API

POST /v3/mail/send di SendGrid diventa POST /v2/emails. La richiesta è più piatta: non ci sono personalizations, e gli indirizzi sono semplici stringhe.

curl https://api.sendgrid.com/v3/mail/send \
  -H "Authorization: Bearer $SENDGRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "personalizations": [{ "to": [{ "email": "ada@example.com" }] }],
    "from": { "email": "hello@acme.com", "name": "Acme" },
    "subject": "Your receipt",
    "content": [
      { "type": "text/plain", "value": "Thanks for your order." },
      { "type": "text/html", "value": "<p>Thanks for your order.</p>" }
    ]
  }'

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",
    "subject": "Your receipt",
    "text": "Thanks for your order.",
    "html": "<p>Thanks for your order.</p>"
  }'

Ogni destinatario di una richiesta Emailit diventa un’email a sé, con il proprio ID. Per inviare variabili diverse a persone diverse, cosa che SendGrid fa con più personalizations, invia una richiesta per destinatario. Aggiungi un header Idempotency-Key così i nuovi tentativi sono sicuri. Vedi Invia un’email.

Cambia le impostazioni SMTP

Emailit non legge l’header X-SMTPAPI. Rimuovilo e imposta invece il tracciamento sul dominio. Vedi Impostazioni SMTP.

Fai corrispondere gli eventi webhook

Come SendGrid, Emailit invia un array JSON di eventi. I campi sono diversi:

• Il nome dell’evento è in type, e l’email è in data.object. Usa data.object.id (l’ID em_ della risposta all’invio) al posto di sg_message_id, e data.object.to al posto di email.
• I tuoi valori meta tornano in data.object.meta.
• Emailit firma le richieste con HMAC-SHA256 invece che con la chiave pubblica ECDSA di SendGrid. Verifica X-Emailit-Signature con il tuo secret whsec_. Vedi Verifica le firme dei webhook.

for (const event of req.body) {
  const email = event.data.object;
  if (event.type === 'email.bounced') markBounced(email.to, email.id);
  if (event.type === 'email.complained') unsubscribe(email.to);
}

Sposta le soppressioni

1. In SendGrid, esporta Bounces, Spam Reports, Invalid Emails e Global Unsubscribes, dalle pagine delle suppressions o con gli endpoint API /v3/suppression/*. I blocks di solito sono temporanei, quindi puoi escluderli.

2. Crea un unico CSV con le colonne email,type,reason:

   CSV

   email,type,reason
   old-address@example.com,recipient,sendgrid bounce
   angry@example.com,recipient,sendgrid spam report

   Usa il tipo recipient per gli indirizzi che non devono mai ricevere email. Blocca gli invii via API, SMTP e campagne. I tipi bounce, complaint e unsubscribe fermano solo le campagne.

3. In Email API›Suppressions, seleziona Import e carica il file. Ogni file può avere fino a 10.000 righe e pesare al massimo 8 MB, quindi dividi le liste più grandi. I duplicati vengono saltati.

Per le disiscrizioni dai gruppi delle email di marketing, importa quelle persone come contatti con unsubscribed impostato, invece di sopprimerle da tutte le email. Vedi Gestisci le soppressioni.

Sposta i template

Esporta l’HTML di ogni dynamic template da SendGrid, poi importalo in Email Marketing›Templates o crealo con l’API dei template. Assegna a ogni template un alias, come receipt, e invialo con "template": "receipt".

Entrambi usano le doppie parentesi graffe, ma Temple è più ridotto di Handlebars:

Vedi Temple e Importa ed esporta i template.

Cambia i DNS

Aggiungi il dominio in Email API›Domains e pubblica i record di Emailit. Usano nomi propri (emailit._domainkey, emailit.<domain> e, facoltativamente, go e inbound), quindi non entrano in conflitto con i CNAME di domain authentication o di link branding di SendGrid. Mantieni il record DMARC. Dopo il passaggio, rimuovi i CNAME di SendGrid. Vedi Record DNS.

Se usavi Inbound Parse, punta a Emailit il record MX del tuo hostname di parse. Per mantenere lo stesso hostname, come parse.acme.com, imposta l’inbound_key del dominio su parse con l’API. Vedi Configura le email in entrata.

Passaggi successivi

• Checklist per andare in produzione
• Configura un webhook
• Migrazione prioritaria: lascia che i tecnici di Emailit facciano la migrazione insieme a te