Guida
Scegli tra API e SMTP
Confronta funzione per funzione l’API REST e l’SMTP relay di Emailit, dai template e la programmazione all’idempotenza e ai webhook, e scegli quello giusto.
Emailit accetta le email transazionali in due modi: l’API REST e l’SMTP relay. Questa guida li confronta per aiutarti a sceglierne uno, oppure a usarli entrambi nello stesso workspace.
La risposta breve
- Usa l’API per il codice nuovo. Fa di più: template, programmazione, nuovi tentativi idempotenti, metadati, impostazioni di tracciamento per singola email e una risposta JSON con un ID per ogni destinatario.
- Usa SMTP quando il software che usi ha già le impostazioni SMTP, come un CMS, il mailer di un framework, un help desk, un dispositivo o un’app legacy. Cambi quattro impostazioni e hai finito.
Entrambi usano le stesse chiavi API, gli stessi domini verificati, la stessa lista di soppressione, gli stessi limiti di invio, log e webhook. Puoi cambiare in seguito senza toccare i DNS.
Confronto delle funzioni
| Funzione | API REST | SMTP relay |
|---|---|---|
| Endpoint | POST https://api.emailit.com/v2/emails |
smtp.emailit.com, porte 587, 465, 2525, 2587 e 25 |
| Autenticazione | Authorization: Bearer secret_… |
AUTH PLAIN o LOGIN, nome utente emailit, password = chiave API |
| Contenuto | html, text o un template memorizzato |
Un messaggio MIME completo, inviato così com’è |
| Template e variabili | template (ID o alias) più variables, elaborati con Temple |
Non disponibili. Elabora il messaggio prima di inviarlo. |
| Programmazione | scheduled_at con ISO 8601, un timestamp Unix o inglese semplice come tomorrow at 9am |
Non disponibile. L’email viene messa in coda subito. |
| Allegati | content in Base64 o un url che Emailit scarica (fino a 25 MB ciascuno). content_id rende un’immagine inline. |
Parti MIME standard |
| Dimensione del messaggio | 40 MB | 40 MB |
| Destinatari per messaggio | Fino a 50 ciascuno in to, cc e bcc |
Nessun limite fisso per transazione |
| Idempotenza | Header Idempotency-Key, con la risposta riproposta per 24 ore |
Non disponibile. Una transazione ritentata può inviare due volte. |
| Metadati | Oggetto meta, restituito nei payload dei webhook |
Non disponibili |
| Header personalizzati | Oggetto headers |
Qualsiasi header nel messaggio |
| Tracciamento di aperture e clic | Per singola email con tracking, o l’impostazione predefinita del dominio |
Solo l’impostazione predefinita del dominio |
Webhook email.accepted e email.scheduled |
Sì | No. Gli eventi successivi come email.delivered ed email.bounced funzionano allo stesso modo. |
| ID delle email | La risposta contiene id, e ids con un ID per destinatario |
Risposta finale 250 2.0.0 OK: queued as em_… |
| Errori | Codici di stato HTTP con un corpo JSON | Codici di risposta SMTP, ad esempio 535 o 550 |
| Limiti di invio | Condivisi a livello di workspace. 429 con gli header ratelimit-* e retry-after. |
Condivisi a livello di workspace. Risposte 452. |
| Crediti | 1 per destinatario | 1 per destinatario |
| Log delle richieste | Email APILogs, origine API | Email APILogs, origine SMTP |
Dopo che un’email è stata accettata, i due canali si comportano allo stesso modo. Ogni destinatario riceve un ID em_, compare in Email APIEmails e l’email si può annullare, ritentare o inoltrare dal pannello o con l’API.
Quando usare l’API
Scegli l’API quando scrivi tu il codice di invio, soprattutto se ti serve una di queste funzioni:
- Template. I designer modificano un template nel pannello e il tuo codice lo invia tramite alias con
variables. Vedi Template. - Nuovi tentativi sicuri. Invia un
Idempotency-Keycon ogni richiesta e ritenta in caso di errori di rete senza inviare due volte. Vedi Idempotenza. - Programmazione. Invia un promemoria per domattina senza una tua coda di job, e riprogrammalo o annullalo fino a 3 minuti prima dell’invio. Vedi Programmazione.
- Correlazione. Allega i tuoi ID in
metae abbina gli eventi dei webhook ai tuoi record. Vedi Header e metadati. - Errori chiari. Un
422per un dominio non verificato o un402per crediti insufficienti sono più facili da gestire di una stringa di risposta SMTP.
Quando usare SMTP
Scegli SMTP quando non puoi o non vuoi modificare il codice:
- Software pronto all’uso come WordPress, un help desk o uno strumento di monitoraggio con una pagina di impostazioni SMTP.
- Mailer dei framework che funzionano già via SMTP, come Laravel, Rails, Django o Nodemailer. Puoi passare all’API in seguito.
- Migrazioni rapide da un altro provider. Sostituisci host, porta, nome utente e password, poi prova.
- Dispositivi e script che parlano solo SMTP, come stampanti, scanner o cron job.
Cose da sapere prima di affidarti a SMTP:
- Via SMTP, Emailit non legge gli header specifici di altri provider. Il tracciamento segue le impostazioni Track loads e Track clicks del dominio di invio.
- Emailit sostituisce l’header
Message-IDcon il proprio e rimuove l’headerReply-Toquando è uguale aFrom. - Usa sempre TLS. È consigliata la porta 587 con STARTTLS, e la 465 usa TLS fin dal primo byte. Vedi Impostazioni SMTP.
Usali entrambi
Molti team li usano entrambi: l’API per le email dell’applicazione e SMTP per un CMS o per gli strumenti interni. Usa una chiave API separata per ciascuno, così li distingui nei log e puoi rigenerarne una senza interrompere l’altra. Una chiave Sending Only limitata a un dominio è adatta alle credenziali SMTP memorizzate in software di terze parti. Vedi Chiavi API.