Come inviare e-mail con PHP utilizzando Twilio SendGrid e Mezzio

Pubblicato: 2021-03-24

L'e-mail è uno strumento di comunicazione importante come sempre. Per aiutarti a sfruttare meglio la posta elettronica, ti mostrerò come inviare e-mail utilizzando il framework Mezzio di PHP e l'API di Twilio SendGrid.

In particolare, imparerai come inviare e-mail con corpi sia in testo normale che HTML e ciò include un allegato PDF. Imparerai anche come utilizzare la funzionalità dei modelli transazionali di Twilio SendGrid per semplificare la creazione di corpi di posta elettronica sia dal team di sviluppo che da qualsiasi altro team all'interno della tua organizzazione.

Suona bene? Cominciamo.

Panoramica rapida dell'applicazione

Per rendere questo tutorial più significativo, fai finta che il codice che scriveremo faccia parte di un negozio di e-commerce online fittizio creato con Mezzio, chiamato The Little PHP Shop , in particolare la parte immediatamente dopo che un cliente ha effettuato un acquisto. A quel punto nel flusso dell'utente, il cliente riceve un'e-mail, in cui lo ringrazia per l'acquisto, e include una fattura PDF per i suoi archivi.

Creeremo una classe Handler per inviare l'e-mail post-acquisto, che riceverà i dettagli dell'acquisto da un ordine completato dal cliente. Con tali informazioni sull'acquisto, la classe Handler utilizzerà quindi diverse classi nell'API PHP SendGrid per creare e inviare l'e-mail di conferma dell'acquisto.

Di questi, i più importanti sono "SendGrid\Mail\Mail" e "\SendGrid". “SendGrid\Mail\Mail” è l'oggetto che memorizza tutte le proprietà di un messaggio di posta elettronica che invieremo tramite Twilio SendGrid. L'oggetto “SendGrid” costituisce il livello di trasporto, facilitando l'invio di email tramite Twilio SendGrid.

Prerequisiti

Per completare questo tutorial, avrai bisogno delle seguenti 4 cose nel tuo ambiente di sviluppo locale:

  1. Account Twilio SendGrid
  2. PHP 7.4 con le estensioni cURL , mbstring e O pen SSL installate e abilitate
  3. Compositore installato a livello globale
  4. arricciare

Impalcatura dell'applicazione Mezzio

Per prima cosa dobbiamo creare l'applicazione di base. Per farlo, useremo, come sempre, il Mezzio Skeleton per farlo per noi. Dopo aver impalcato l'applicazione di base, passeremo alla directory del progetto appena creata. Quindi esegui i seguenti comandi nel tuo terminale, seguendo le istruzioni per il primo:

Installa le dipendenze richieste

Con il progetto impalcato, dobbiamo aggiungere 3 dipendenze aggiuntive per completare il progetto. Questi sono:

  • Libreria API PHP di Twilio SendGrid per l'interazione con l'API Twilio SendGrid
  • Client HTTP PHP per l'invio di richieste HTTP
  • PHP Dotenv per la memorizzazione e il recupero di variabili d'ambiente

Per installarli, esegui il seguente comando nel tuo terminale:

Inizializza PHP Dotenv

Con le dipendenze installate, carichiamo PHP Dotenv in modo che legga le variabili impostate in “.env” e le metta a disposizione di PHP come variabili di ambiente. Per farlo, inserisci il seguente codice in "public/index.php", subito dopo "require vendor/autoload.php".

Aggiungi i dettagli del tuo account Twilio SendGrid

Ora devi fornire all'applicazione la tua chiave API SendGrid. Per farlo, dopo aver effettuato l'accesso a Twilio SendGrid , vai su "Impostazioni -> Chiavi API ". " Una volta lì:

  1. Fare clic su " Crea chiave API " per creare una chiave API
  2. Assegna un nome alla nuova chiave API, accetta l'autorizzazione della chiave API predefinita di " Accesso completo " e fai clic su " Crea e visualizza "

Con la chiave API creata, fai clic e copia la chiave, quindi fai clic su " Fatto . "

Successivamente, aggiungi altre 2 chiavi al file: "SENDGRID_DEFAULT_SENDER_ADDRESS" e "SENDGRID_DEFAULT_SENDER_NAME". Come indicano i nomi, questi sono l'indirizzo e-mail e il nome che utilizzeremo per tutte le e-mail inviate dalla nostra applicazione a meno che non vengano sovrascritte.

Nota: Per fare ciò, in Autenticazione mittente , assicurati che sia indicato "Verificato" nella tabella "Verifica mittente singolo".

Imposta i dettagli di configurazione della posta dell'applicazione

Oltre alla chiave API Twilio SendGrid, memorizzeremo alcune altre impostazioni di configurazione della posta globale. In particolare, imposteremo un indirizzo da e risponderemo all'indirizzo e-mail e al nome che utilizzeremo in ogni messaggio e-mail. In questo modo, non dobbiamo impostarli ogni volta.

Creeremo anche 2 modelli per il corpo dell'e-mail: uno per le e-mail in testo normale e uno per le e-mail HTML. Per fare ciò, in "config/autoload" crea un nuovo file chiamato "mail.global.php" e in esso aggiungi il codice seguente.

Crea una classe per creare un'istanza di un oggetto di posta

Con i dettagli di configurazione dell'applicazione chiave impostati, creiamo ora una classe che istanzia un oggetto di posta di base con le proprietà predefinite impostate. Per fare ciò, in una nuova directory, "src/App/src/Mailer", crea un nuovo file chiamato "SendGridMailMessageFactory.php" e in esso aggiungi il codice seguente.

Quando invochiamo la classe, ha accesso al contenitore DI (Dependency injection) dell'applicazione, da cui recupererà i dettagli di configurazione che abbiamo archiviato in "config/autoload/mail.global.php".

Successivamente, creerà un'istanza di un nuovo oggetto "SendGrid\Mail\Mail" e imposterà da e risponderà ai dettagli passando i rispettivi dettagli di configurazione alle chiamate rispettivamente ai metodi "Mail", "setFrom" e "setReplyTo". Successivamente, restituirà l'oggetto "Mail" istanziato.

Per usarlo, però, devi registrarlo con il contenitore DI. Per fare ciò, in "src/App/src/ConfigProvider", aggiungi la seguente voce all'elemento "factory" nell'array restituito dal metodo "getDependencies".

Crea un gestore per inviare e-mail

Successivamente dobbiamo creare una classe Handler per comporre e inviare e-mail. Per fare ciò, utilizzeremo gli strumenti CLI di Mezzio , disponibili tramite Composer, eseguendo il comando seguente.

L'esecuzione del comando sopra fa quattro cose per noi:

  1. Crea una nuova classe Handler, “src/App/Handler/EmailSenderHandler.php ”
  2. Crea una classe factory per creare un'istanza della classe Handler, "src/App/Handler/EmailSenderHandlerFactory.php"
  3. Crea un file modello ("src/App/templates/app/email-sender.html.<ext>"), di cui non avremo bisogno . Il nome del file "<ext>" è determinato dal motore del modello scelto durante la fase di "creazione del progetto".
  4. Registra la nuova classe Handler come servizio nel contenitore DI aggiungendo una voce a "config/autoload/mezzio-tooling-factory.global.php"

Refactoring del gestore per inviare e-mail

Con "EmailSenderHandler.php" creato, ora dobbiamo rifattorizzarlo in modo che possa inviare e-mail. Per fare ciò, faremo prima il refactoring del costruttore "EmailSenderHandler's", sostituendo il parametro "TemplateRendererInterface" con 3 nuovi parametri. Questi inizializzeranno 3 nuove variabili dei membri della classe:

  • Un oggetto "\SendGrid\Mail\Mail".
  • Un oggetto "\SendGrid".
  • Un array contenente i dettagli di configurazione richiesti

Puoi vedere il costruttore rivisto nell'esempio seguente, insieme alle relative variabili dei membri della classe. Sostituisci la variabile del membro della classe esistente e il costruttore con questo codice.

Nota: Successivamente, dobbiamo rifattorizzare il metodo "handle". Sostituisci il contenuto esistente del metodo "handle" "EmailSenderHandler" con il codice seguente, quindi esaminiamo ciò che fa.

Inizia utilizzando "$request->getParsedBody()" per recuperare tutti i parametri forniti nel corpo della richiesta, che restituirà un array associativo, inizializzando "$details". Con i parametri disponibili, chiama il metodo “addTo” dell'oggetto “SendGrid\Mail\Mail” per impostare il destinatario dell'e-mail, passando l'indirizzo e-mail e il nome del destinatario nei primi 2 argomenti e un array di sostituzioni nel terzo argomento.

Le sostituzioni consentono di personalizzare i messaggi di posta elettronica per ciascun destinatario. Nelle e-mail in testo normale, qualsiasi stringa immediatamente racchiusa da trattini, ad esempio "-first_name-" è una sostituzione. Nelle e-mail HTML, utilizza la sintassi Handlebars , che racchiude le stringhe tra parentesi doppie, ad esempio "{{ first_name }}".

Successivamente, impostiamo l'oggetto del messaggio e aggiungiamo un corpo del messaggio in testo normale e HTML. Con ciò, la nostra e-mail è pronta per essere inviata. Quindi utilizziamo l'oggetto "SendGrid", "$this->mailer", per inviarlo, inizializzando una nuova variabile, "$response", con la risposta dal tentativo di inviare il messaggio. Infine, restituiamo un oggetto JsonResponse , contenente il codice di stato e il corpo della risposta.

Nota: Refactor EmailSenderHandlerFactory metodo __invoke

Ora che abbiamo completato il refactoring di "EmailSenderHandler", è necessario eseguire il refactoring di "EmailSenderHandlerFactory". Questo istanzia correttamente "EmailSenderHandler". Per fare ciò, sostituisci la definizione esistente del suo metodo "__invoke`" con il codice seguente.

Questo recupera un oggetto "\SendGrid\Mail\Mail" dal contenitore DI, preinizializzato con il mittente e risponde ai dettagli dell'e-mail e inizializza un nuovo oggetto denominato "$messaggio". Quindi crea un'istanza di un nuovo oggetto "SendGrid", chiamato "$mailer" per l'invio del messaggio di posta. Infine, recupera la configurazione della posta dalla configurazione dell'applicazione. Quindi, li usa per inizializzare e restituire l'oggetto "EmailSenderHandler".

Aggiorna la tabella di instradamento

Con tutte queste modifiche, c'è un'ultima modifica da apportare prima di poter testare il codice e inviare un'e-mail. Dobbiamo aggiornare la tabella di routing in modo che la route predefinita utilizzi la nostra nuova classe Handler come gestore della route, invece di "HomePageHandler". Per fare ciò, sostituisci la definizione del percorso predefinito in "config/routes.php" con il seguente esempio.

Invia la prima e-mail

Ora è il momento di inviare la prima email. Per farlo, per prima cosa, avvia l'applicazione eseguendo il comando seguente nel terminale.

Quindi, utilizzando cURL, fai una richiesta GET a " http://localhost:8080 ", come nell'esempio seguente, sostituendo i valori tra parentesi angolari con i dettagli pertinenti per la tua email.

Dovresti vedere l'output "{"status":202,"message":""}" sul terminale e dovresti ricevere un'e-mail simile all'immagine qui sotto.

Nota: Utilizza modelli di email transazionali invece di stringhe di modelli

Sebbene siamo stati in grado di inviare un'e-mail sia con un testo in chiaro che con un corpo HTML, il modo in cui l'abbiamo fatto, tuttavia, non è l'ideale. Per ogni e-mail che inviamo, e la nostra applicazione potrebbe finire per inviarne un bel po', dovremo aggiungere un testo in chiaro e un corpo HTML per loro.

Ma l'archiviazione delle definizioni del corpo dell'e-mail nel codice pone la maggior parte dello sforzo sul team di sviluppo. Tuttavia, almeno nella mia esperienza, capita spesso che altri team, spesso di marketing, creino e mantengano modelli di email.

Quindi, per questo motivo, e poiché accelererebbe lo sviluppo e condivideremo il carico tra più team, riformuleremo l'applicazione per utilizzare modelli di email transazionali . Puoi crearli e gestirli tramite l'interfaccia utente di Twilio SendGrid da parte di membri del team che potrebbero avere poca o nessuna esperienza tecnica, invece che nel codice.

Se non ne hai sentito parlare, il glossario Twilio SendGrid li definisce come segue:

I modelli e-mail transazionali sono layout e-mail precodificati che esperti di marketing, designer e sviluppatori possono utilizzare per creare rapidamente e facilmente campagne e-mail transazionali. I modelli di e-mail transazionali di Twilio SendGrid consentono a persone non tecniche e tecniche di apportare modifiche in tempo reale alle e-mail ricevute dai destinatari.

Per questo articolo, abbiamo solo bisogno di uno abbastanza semplice. Per farlo, segui i dettagli nella documentazione di Twilio SendGrid e creane uno che abbia come contenuto solo un modulo a testo singolo. Quindi, per il corpo del testo, usa il testo seguente.

Nota che ci sono 6 sostituzioni nell'e-mail:

  • “first_name”: il nome del cliente
  • “cognome”: il cognome del cliente
  • “sender_name”: il nome del negozio di e-commerce (The Little PHP Shop)
  • “sender_state”: lo stato del negozio di e-commerce
  • “sender_country”: il paese del negozio di e-commerce
  • "support_email": l'e-mail di supporto che i clienti possono utilizzare per ottenere supporto post-vendita

Detto questo, dobbiamo rendere tali informazioni disponibili alla nostra applicazione. Abbiamo già il nome e il cognome del cliente. Le restanti 4 sostituzioni saranno globali, quindi, come abbiamo fatto in precedenza, aggiungeremo la configurazione di seguito a " config/autoload/mail.global.php ", dopo l'elemento "templates".

Con il nuovo file di configurazione creato, nel metodo "handle" "EmailSenderHandler", sostituisci le 2 chiamate a "$this->mail->addContent()" con il codice seguente.

Le 2 chiamate al metodo aggiungono i dettagli del mittente e supportano l'indirizzo e-mail come sostituzioni globali. Queste sostituzioni si applicano al corpo dell'e-mail prima di qualsiasi altra sostituzione, ma vengono ignorate se sono presenti sostituzioni con la stessa chiave per un destinatario dell'e-mail.

Successivamente, è necessario recuperare l'ID del modello di email transazionale. Puoi trovarlo facendo clic sul nome del modello nell'elenco dei modelli , come puoi vedere nello screenshot qui sotto.

Copialo e salvalo in "config/autoload/mail.global.php" in un nuovo elemento con la chiave "template_id" e quindi rimuovi "plain" e "HTML". Al termine, l'elemento "mail/templates" dell'array restituito sarà simile al codice seguente, dove "<the template's id>" sostituisce l'ID del modello.

Con la configurazione aggiornata, ora dobbiamo aggiungere una chiamata al metodo "Mail" "setTemplateId" nel metodo "handle" "EmailSenderHandler", passando l'ID del modello che abbiamo appena aggiunto a "config/autoload/mail.global. php." Puoi vedere un esempio nel codice qui sotto.

Proviamo le modifiche

Come prima, usando cURL, fai una richiesta GET a " http://localhost:8080 " per verificare se le modifiche funzionano come previsto. Dovresti vedere l'output "{"status":202,"message":""}" sul terminale, come nell'esempio precedente. Nella tua casella di posta elettronica, dovresti vedere una bella e-mail, con le sostituzioni sostituite, come nello screenshot qui sotto.

Allega fattura PDF

Ora che utilizziamo i modelli dinamici, alleghiamo la fattura PDF di cui abbiamo parlato all'inizio dell'articolo. Per risparmiare tempo e fatica nella ricerca o nella creazione di uno stesso, ho creato una fattura PDF di esempio che puoi utilizzare per questo articolo. Salvalo nella directory " data" dell'applicazione .

Nota: Per allegare una fattura, dobbiamo utilizzare il metodo "Mail" "addAttachment", che puoi vedere nel prossimo esempio di codice. Il metodo accetta 5 argomenti, ma forniamo solo i primi 4. Questi sono:

  1. Un oggetto " Allegato" o una stringa codificata Base64 . Se il valore di questo parametro non è codificato in base64, il metodo lo farà per noi.
  2. Il tipo mime dell'allegato (ora noto come tipo di supporto ).
  3. Il nome del file dell'allegato . Questo è il nome con cui il file salverà, per impostazione predefinita, a meno che l'utente non lo modifichi.
  4. Disposizione del contenuto dell'allegato . Se non si ha familiarità con la disposizione del contenuto, la disposizione del contenuto in linea significa che l'allegato deve essere visualizzato automaticamente quando viene visualizzato il messaggio e la disposizione del contenuto dell'allegato significa che l'allegato non viene visualizzato automaticamente e richiede una qualche forma di azione da parte dell'utente per aprilo.

Nell'esempio di codice seguente, il metodo file_get_contents di PHP legge il contenuto del file in una nuova variabile denominata "$fattura". Quindi, il PDF si allega al messaggio chiamando il metodo "addAttachment".

Qui noi:

  • Trasmetti il ​​contenuto della fattura, che sarà codificata in Base64
  • Imposta il tipo MIME su "application/pdf" mentre alleghiamo un file PDF
  • Imposta il nome del file della fattura su un nome fittizio che un cliente potrebbe ragionevolmente aspettarsi
  • Imposta la disposizione del contenuto su "allegato"

Ora che abbiamo terminato queste modifiche, testiamo che funzionino. Esegui la stessa richiesta cURL che abbiamo eseguito le 2 volte precedenti. Quindi, nella tua casella di posta elettronica, dovresti vedere una bella e-mail con l'esempio di fattura PDF visibile durante la visualizzazione dell'e-mail.

Ecco come inviare e-mail con PHP utilizzando Twilio SendGrid e Mezzio

Mentre abbiamo solo scalfito la superficie di ciò che è possibile durante l'invio di e-mail con Twilio SendGrid e Mezzio, ora puoi inviare un'e-mail con un testo normale e un corpo HTML, nonché con un allegato. Hai anche imparato a utilizzare i modelli transazionali e le sostituzioni che puoi impostare a livello globale e in base al destinatario.

Ti consiglio vivamente di dare un'occhiata alla documentazione della libreria PHP per vedere cos'altro è disponibile, come la pianificazione degli invii di e-mail, l'allegato di un file da Amazon S3, l'aggiunta di intestazioni e l'aggiunta di sezioni e categorie.

Matthew Setter è un editor PHP nel team di Twilio Voices e, naturalmente, uno sviluppatore PHP. È anche autore di Mezzio Essentials . Quando non scrive codice PHP, pubblica ottimi articoli PHP qui su Twilio. Può essere raggiunto tramite:

  • E-mail: [email protected]
  • Web: http://matthewsetter.com
  • Twitter: @settermjd
  • GitHub: https://github.com/settermjd