Как отправить электронную почту с помощью PHP, используя Twilio SendGrid и Mezzio

Опубликовано: 2021-03-24

Электронная почта является таким же важным средством коммуникации, как и прежде. Чтобы помочь вам лучше использовать электронную почту, я собираюсь показать вам, как отправлять электронную почту с помощью среды PHP Mezzio и API Twilio SendGrid.

В частности, вы узнаете, как отправлять электронные письма как с открытым текстом, так и с телом HTML, включая вложение в формате PDF. Вы также узнаете, как использовать функциональные возможности транзакционных шаблонов Twilio SendGrid, чтобы упростить создание тела электронной почты как командой разработчиков, так и любой другой командой в вашей организации.

Звучит неплохо? Давай начнем.

Краткий обзор приложений

Чтобы сделать это руководство более содержательным, представьте, что код, который мы напишем, является частью вымышленного онлайн-магазина электронной коммерции, созданного с помощью Mezzio, под названием The Little PHP Shop , в частности, часть сразу после того, как покупатель совершает покупку. В этот момент пользовательского потока клиент получает электронное письмо с благодарностью за покупку и включает счет в формате PDF для своих записей.

Мы собираемся создать класс Handler для отправки электронного письма после покупки, которое будет получать информацию о покупке из заказа, выполненного покупателем. С этой информацией о покупке класс Handler затем будет использовать несколько классов в PHP API SendGrid для создания и отправки электронного письма с подтверждением покупки.

Из них наиболее важными являются «SendGrid\Mail\Mail» и «\SendGrid». «SendGrid\Mail\Mail» — это объект, в котором хранятся все свойства сообщения электронной почты, которое мы отправляем через Twilio SendGrid. Объект «SendGrid» формирует транспортный уровень, упрощая отправку электронных писем через Twilio SendGrid.

Предпосылки

Для выполнения этого руководства вам потребуются следующие 4 вещи в вашей локальной среде разработки:

  1. Учетная запись Twilio SendGrid
  2. PHP 7.4 с установленными и включенными расширениями cURL , mbstring и Open SSL .
  3. Композитор установлен глобально
  4. CURL

Создание шаблона приложения Mezzio

Сначала нам нужно создать базовое приложение. Для этого мы, как всегда, будем использовать Mezzio Skeleton , который сделает это за нас. Как только мы создадим базовое приложение, мы переключимся на только что созданный каталог проекта. Затем выполните следующие команды в своем терминале, следуя подсказкам для первой:

Установите необходимые зависимости

Когда проект создан, нам нужно добавить 3 дополнительные зависимости для завершения проекта. Эти:

  • Библиотека PHP API Twilio SendGrid для взаимодействия с API Twilio SendGrid.
  • HTTP-клиент PHP для отправки HTTP-запросов
  • PHP Dotenv для хранения и извлечения переменных окружения

Чтобы установить их, выполните следующую команду в своем терминале:

Инициализировать PHP Dotenv

С установленными зависимостями мы загружаем PHP Dotenv, чтобы он прочитал переменные, установленные в «.env», и сделал их доступными для PHP в качестве переменных среды. Для этого вставьте следующий код в «public/index.php» сразу после «require vendor/autoload.php».

Добавьте данные своей учетной записи Twilio SendGrid.

Теперь вам нужно предоставить приложению ключ API SendGrid. Для этого после входа в Twilio SendGrid перейдите в «Настройки -> Ключи API ». " Когда-то:

  1. Нажмите « Создать ключ API », чтобы создать ключ API.
  2. Дайте новому ключу API имя, примите разрешение ключа API по умолчанию « Полный доступ » и нажмите « Создать и просмотреть » .

Создав ключ API, нажмите и скопируйте ключ, затем нажмите « Готово » . ”

После этого добавьте в файл еще 2 ключа: «SENDGRID_DEFAULT_SENDER_ADDRESS» и «SENDGRID_DEFAULT_SENDER_NAME». Как видно из имен, это адрес электронной почты и имя, которые мы будем использовать для любых электронных писем, отправляемых из нашего приложения, если они не будут переопределены.

Примечание. Для этого в Sender Authentication убедитесь, что в таблице «Single Sender Verification» написано «Verified».

Установить детали конфигурации почты приложения

В дополнение к ключу API Twilio SendGrid мы собираемся сохранить несколько других глобальных параметров конфигурации почты. В частности, мы собираемся установить адрес электронной почты и имя отправителя и ответа на него, которые мы будем использовать в каждом сообщении электронной почты. Таким образом, нам не нужно устанавливать их каждый раз.

Мы также собираемся создать 2 шаблона тела электронной почты: один для электронных писем с открытым текстом и один для электронных писем в формате HTML. Для этого в «config/autoload» создайте новый файл с именем «mail.global.php» и добавьте в него следующий код.

Создайте класс для создания почтового объекта

Установив ключевые детали конфигурации приложения, давайте теперь создадим класс, который будет создавать экземпляр базового почтового объекта с набором свойств по умолчанию. Для этого в новом каталоге «src/App/src/Mailer» создайте новый файл с именем «SendGridMailMessageFactory.php» и добавьте в него приведенный ниже код.

Когда мы вызываем класс, он получает доступ к контейнеру внедрения зависимостей (DI) приложения, из которого он извлекает детали конфигурации, которые мы сохранили в «config/autoload/mail.global.php».

После этого он создаст экземпляр нового объекта «SendGrid\Mail\Mail» и установит детали отправителя и ответа, передав соответствующие детали конфигурации в вызовы методов «Mail», «setFrom» и «setReplyTo» соответственно. После этого он вернет созданный экземпляр объекта «Почта».

Однако, чтобы использовать его, вы должны зарегистрировать его в контейнере DI. Для этого в «src/App/src/ConfigProvider» добавьте следующую запись в элемент «factories» в массиве, возвращаемом методом «getDependencies».

Создайте обработчик для отправки электронной почты

Затем нам нужно создать класс Handler для составления и отправки электронных писем. Для этого мы воспользуемся инструментом командной строки Mezzio , доступным через Composer, выполнив приведенную ниже команду.

Выполнение приведенной выше команды делает для нас четыре вещи:

  1. Создает новый класс Handler, «src/App/Handler/EmailSenderHandler.php» .
  2. Создает фабричный класс для создания экземпляра класса Handler, «src/App/Handler/EmailSenderHandlerFactory.php».
  3. Создает файл шаблона («src/App/templates/app/email-sender.html.<ext>»), который нам не понадобится . Имя файла «<ext>» определяется механизмом шаблонов, который вы выбрали на этапе «создать проект».
  4. Регистрирует новый класс Handler как службу в контейнере DI, добавляя запись в «config/autoload/mezzio-tooling-factories.global.php».

Рефакторинг обработчика для отправки электронных писем

Создав «EmailSenderHandler.php», нам нужно реорганизовать его, чтобы он мог отправлять электронные письма. Для этого мы сначала проведем рефакторинг конструктора «EmailSenderHandler», заменив параметр «TemplateRendererInterface» тремя новыми параметрами. Они инициализируют 3 новые переменные-члены класса:

  • Объект «\SendGrid\Mail\Mail»
  • Объект «\SendGrid»
  • Массив, содержащий необходимые детали конфигурации

Вы можете увидеть измененный конструктор в приведенном ниже примере вместе с соответствующими переменными-членами класса. Замените существующую переменную-член класса и конструктор этим кодом.

Примечание. Далее нам нужно провести рефакторинг метода «handle». Замените существующее содержимое метода «дескриптора» «EmailSenderHandler» приведенным ниже кодом, затем давайте рассмотрим, что он делает.

Он начинается с использования «$request->getParsedBody()» для получения любых параметров, предоставленных в теле запроса, который возвращает ассоциативный массив, инициализирующий «$details». Имея доступные параметры, он вызывает метод addTo объекта «SendGrid\Mail\Mail», чтобы установить получателя электронной почты, передавая адрес электронной почты и имя получателя в первых двух аргументах и ​​массив замен в третьем аргументе.

Замены позволяют настраивать сообщения электронной почты для каждого получателя. В электронных письмах с открытым текстом любая строка, непосредственно окруженная дефисами, например «-first_name-», является заменой. В электронных письмах в формате HTML он использует синтаксис Handlebars , заключающий строки в двойные круглые скобки, например, «{{ first_name }}».

Затем мы устанавливаем тему сообщения и добавляем текст сообщения и тело сообщения в формате HTML. После этого наше электронное письмо готово к отправке. Поэтому мы используем объект «SendGrid», «$this->mailer», чтобы отправить его, инициализируя новую переменную «$response» с ответом на попытку отправить сообщение. Наконец, мы возвращаем объект JsonResponse , содержащий код состояния и тело ответа.

Примечание. Рефакторинг метода __invoke EmailSenderHandlerFactory

Теперь, когда мы завершили рефакторинг «EmailSenderHandler», нам нужно провести рефакторинг «EmailSenderHandlerFactory». Это позволит правильно создать экземпляр «EmailSenderHandler». Для этого замените существующее определение его метода «__invoke`» следующим кодом.

Это извлекает объект «\SendGrid\Mail\Mail» из контейнера DI, предварительно инициализированный отправителем и ответом на данные электронной почты, и инициализирует новый объект с именем «$message». Затем он создает новый объект «SendGrid» с именем «$mailer» для отправки почтового сообщения. Наконец, он извлекает конфигурацию почты из конфигурации приложения. Затем он использует их для инициализации и возврата объекта «EmailSenderHandler».

Обновите таблицу маршрутизации

Со всеми этими изменениями осталось внести одно последнее изменение, прежде чем мы сможем протестировать код и отправить электронное письмо. Мы должны обновить таблицу маршрутизации, чтобы маршрут по умолчанию использовал наш новый класс Handler в качестве обработчика маршрута, а не «HomePageHandler». Для этого замените определение маршрута по умолчанию в «config/routes.php» следующим примером.

Отправить первое письмо

Теперь пришло время отправить первое электронное письмо. Для этого сначала запустите приложение, выполнив приведенную ниже команду в терминале.

Затем, используя cURL, сделайте запрос GET на « http://localhost:8080 », как в примере ниже, заменив значения в угловых скобках соответствующими данными для вашей электронной почты.

Вы должны увидеть вывод «{«status»:202,«message»:»»}» на терминал, и вы должны получить электронное письмо, похожее на изображение ниже.

Примечание . Вместо этого Используйте шаблоны транзакционной электронной почты вместо строк шаблона

Хотя мы смогли отправить электронное письмо как с открытым текстом, так и с телом HTML, то, как мы это сделали, далеко не идеально. Для каждого письма, которое мы отправляем — а наше приложение может в конечном итоге отправить довольно много — нам нужно будет добавить для них открытый текст и HTML-тело.

Но сохранение определений тела электронной почты в коде возлагает большую часть усилий на команду разработчиков. Однако, по крайней мере, по моему опыту, часто бывает так, что другие команды, часто занимающиеся маркетингом, создают и поддерживают шаблоны электронной почты.

По этой причине, а также потому, что это ускорит разработку и распределит нагрузку между несколькими командами, мы собираемся реорганизовать приложение для использования шаблонов транзакционной электронной почты . Вы можете создавать и поддерживать их с помощью пользовательского интерфейса Twilio SendGrid членами команды, у которых может быть мало или совсем нет технического опыта, а не в коде.

Если вы не слышали о них, глоссарий Twilio SendGrid определяет их следующим образом:

Шаблоны транзакционной электронной почты — это предварительно закодированные макеты электронной почты, которые маркетологи, дизайнеры и разработчики могут использовать для быстрого и простого создания транзакционных почтовых кампаний. Шаблоны транзакционной электронной почты Twilio SendGrid позволяют как нетехническим, так и техническим людям вносить изменения в электронную почту, которую получают их получатели, в режиме реального времени.

Для этой статьи нам нужен только довольно простой. Для этого следуйте инструкциям в документации по Twilio SendGrid и создайте такую, содержимое которой находится только в однотекстовом модуле. Затем в качестве основного текста используйте приведенный ниже текст.

Обратите внимание, что в письме есть 6 замен:

  • «first_name»: имя клиента
  • «last_name»: фамилия клиента
  • «sender_name»: название интернет-магазина (The Little PHP Shop)
  • «sender_state»: состояние интернет-магазина.
  • «sender_country»: страна интернет-магазина.
  • «support_email»: электронная почта поддержки, которую клиенты могут использовать для получения послепродажной поддержки.

Учитывая это, нам нужно сделать эту информацию доступной для нашего приложения. Имя и фамилия клиента у нас уже есть. Остальные 4 подстановки будут глобальными, поэтому, как и раньше, мы добавим приведенную ниже конфигурацию в « config/autoload/mail.global.php » после элемента «templates».

Создав новый файл конфигурации, в методе «handle» «EmailSenderHandler» замените два вызова «$this->mail->addContent()» следующим кодом.

Вызовы двух методов добавляют сведения об отправителе и поддерживают адрес электронной почты в качестве глобальных замен. Эти замены применяются к телу электронной почты до любых других замен, но переопределяются, если есть замены с тем же ключом для получателя электронной почты.

Затем вам нужно получить идентификатор шаблона транзакционной электронной почты. Вы можете найти его, щелкнув имя шаблона в списке шаблонов , как показано на скриншоте ниже.

Скопируйте его и сохраните в «config/autoload/mail.global.php» в новом элементе с ключом «template_id», а затем удалите «обычный» и «HTML». Когда закончите, элемент «mail/templates» возвращаемого массива будет выглядеть так, как показано ниже, где «<id шаблона>» заменяет идентификатор вашего шаблона.

С обновленной конфигурацией нам теперь нужно добавить вызов метода «Mail» «setTemplateId» в методе «handle» «EmailSenderHandler», передав идентификатор шаблона, который мы только что добавили, в «config/autoload/mail.global. php». Вы можете увидеть пример в коде ниже.

Протестируем изменения

Как и прежде, используя cURL, отправьте запрос GET на « http://localhost:8080 », чтобы проверить, работают ли изменения должным образом. Вы должны увидеть вывод «{“status”:202,“message”:””}” на терминал, как и в предыдущем примере. В вашем почтовом ящике вы должны увидеть красивое письмо с замененными заменами, как на скриншоте ниже.

Прикрепить счет в формате PDF

Теперь, когда мы используем динамические шаблоны, давайте прикрепим счет в формате PDF, о котором мы говорили в начале статьи. Чтобы сэкономить ваше время и силы на поиск или создание счета самостоятельно, я создал образец счета в формате PDF , который вы можете использовать в этой статье. Сохраните его в каталоге « data» приложения.

Примечание. Чтобы прикрепить счет, нам нужно использовать метод addAttachment «Mail», который вы можете увидеть в следующем примере кода. Метод принимает 5 аргументов, но мы предоставляем только первые 4. Это:

  1. Объект « Приложение» или строка в кодировке Base64 . Если значение этого параметра не закодировано в base64, метод сделает это за нас.
  2. Mime-тип вложения (теперь известный как media type ).
  3. Имя файла вложения . Это имя, под которым файл будет сохранен по умолчанию, если пользователь не изменит его.
  4. Расположение содержимого вложения . Если вы не знакомы с обработкой содержимого, встроенная раскладка содержимого означает, что вложение должно автоматически отображаться при отображении сообщения, а раскладка содержимого вложения означает, что вложение не отображается автоматически и требует от пользователя каких-либо действий, чтобы Открой это.

В приведенном ниже примере кода метод PHP file_get_contents считывает содержимое файла в новую переменную с именем «$invoice». Затем PDF-файл прикрепляется к сообщению, вызывая метод «addAttachment».

Мы тут:

  • Передайте содержимое счета, которое будет закодировано в Base64.
  • Установите тип MIME на «application/pdf», поскольку мы прикрепляем файл PDF.
  • Установите имя файла счета-фактуры на вымышленное имя, которое клиент мог бы разумно ожидать
  • Установите расположение содержимого на «вложение»

Теперь, когда мы закончили эти изменения, давайте проверим, работают ли они. Запустите тот же запрос cURL, что и предыдущие 2 раза. Затем в папке «Входящие» вы должны увидеть прекрасное электронное письмо с примером счета в формате PDF, видимым при просмотре электронной почты.

Вот как отправлять электронную почту с помощью PHP, используя Twilio SendGrid и Mezzio

Хотя мы только немного коснулись того, что возможно при отправке электронных писем с помощью Twilio SendGrid и Mezzio, теперь вы можете отправлять электронные письма с текстом и телом HTML, а также с вложением. Вы также узнали, как использовать шаблоны транзакций и подстановки, которые можно устанавливать глобально и для каждого получателя.

Я настоятельно рекомендую вам ознакомиться с документацией по библиотеке PHP, чтобы узнать, что еще доступно, например, планирование отправки электронной почты, прикрепление файла из Amazon S3, добавление заголовков и добавление разделов и категорий.

Мэтью Сеттер — редактор PHP в команде Twilio Voices и, естественно, разработчик PHP. Он также является автором Mezzio Essentials . Когда он не пишет PHP-код, он редактирует отличные статьи о PHP здесь, в Twilio. До него можно добраться через:

  • Электронная почта: matthew@matthewsetter.com
  • Интернет: http://matthewsetter.com
  • Твиттер: @settermjd
  • Гитхаб: https://github.com/settermjd