Англійський словник для API перенаправлення електронної пошти

Resend — це розроблений для розробників транзакційний електронний API, побудований для сучасних застосунків. Він безшумно інтегрується з React Email для створення шаблонів електронної пошти як компонентів React, і надає чистий SDK для надсилання електронних листів з Node.js, Python та інших мов. Якщо ваша програма надсилає підтвердження замовлень, скасування паролів, сповіщення або будь- які інші транзакційні повідомлення електронної пошти за допомогою перенаправлення, розуміння її словника допоможе вам чітко спілкуватися з колегами, зневаджувати проблеми з доставкою і розробляти надійні конвеєри електронної пошти. У цьому статті описано основні терміни, з якими ви зіткнетеся під час роботи з пунктом меню Перенадіслати.

Ключовий словник

** send () метод ** Основний метод SDK для надсилання однієї електронної пошти за допомогою перенаправлення. Ви передаєте йому об’єкт з from, to, subject, і або html, text, або react (компонент React Email). Він повертає обіцянку, яка розв’язується до об’єкта, що містить надіслану електронну пошту id. Приклад: “Викликати resend.emails.send() з компонентом React Email для привітального листа — повернений id є тим, що ви зберігаєте в базі даних для відстеження стану доставки.”

** від / до / тема ** Три обов’ язкові поля у кожному виклику send(). from має бути адресою у перевіреному домені. to приймає рядок або масив рядків для декількох адресатів. subject — це рядок теми електронної пошти, який буде показано у вхідній теці. Приклад: «Адреса from повинна відповідати домену, який ви перевірили у вашому обліковому записі Перенаправлення — використання адреси Gmail або неперевіреного домену призведе до невдачі надсилання з помилкою авторизації.»

** Реакція на електронну пошту ** Бібліотека з відкритим кодом (супроводжується командою Resend) для створення шаблонів електронної пошти за допомогою компонентів React. Замість написання сирих таблиць HTML і вбудованих стилів, ви можете складати електронні листи з попередньо створених компонентів, таких як <Button>, <Text>, <Section> і <Hr>. React Email відтворює електронну пошту у HTML-форматі, сумісному з електронною поштою, під час надсилання. Приклад: «Ми використовуємо React Email для створення всіх транзакційних шаблонів — компоненти <Button> і <Text> обробляють крос-клієнтське відтворення, тому нам не потрібно писати HTML на основі таблиць вручну.»

** Перевірка домену ** Процес перенаправлення, який доводить, що ви є власником домену, з якого ви бажаєте надсилати електронну пошту, і керуєте цим доменом. Для цього потрібно додати записи DNS (SPF, DKIM і, за бажанням, DMARC) до налаштувань DNS вашого домену. Неперевірені домени не можуть бути використані в полі from.

• Приклад: « Перевірка домену блокує запуск — додайте записи SPF і DKIM до постачальника DNS, а потім натисніть кнопку « Перевірити » на панелі « Повторне надсилання ». Зазвичай вона поширюється протягом декількох хвилин.»*

** Веб- гаки ** Зворотні виклики HTTP, які програма Resend надсилає до вашої програми, коли відбуваються події електронної пошти. Ключові події включають email.delivered, email.bounced, email.complained (спам-звіт) і email.opened. Ви можете зареєструвати кінцеву точку webhook у параметрах облікового запису Перенадіслати і обробляти ці події для відстеження можливості доставки і оновлення записів користувача.

• Приклад: « Налаштувати кінцеву точку webhook для подій email.bounced — коли ми отримаємо відскок, ми повинні позначити адресу електронної пошти користувача як невірну в базі даних і припинити надсилання на неї ». *

email.delivered / email.bounced Два найважливіших типи подій webhook Перенадіслати. email.delivered підтверджує, що поштовий сервер- отримувач прийняв повідомлення. email.bounced вказує на те, що повідомлення було відхилено — або як жорстке відхилення (неправильна адреса), або як м’ яке відхилення (тимчасова помилка, наприклад, переповнення скриньки вхідних). Приклад: «Ми бачимо 4% відсоток відскоків у кампанії — фільтрувати події email.bounced webhook за типом відскоку, щоб відокремити жорсткі відскоки (неправильні адреси) від м’яких відскоків (тимчасові помилки) і обробляти їх по-різному.»

** Пакетне надсилання ** API Resend для надсилання декількох листів електронної пошти за допомогою одного виклику API — до 100 листів електронної пошти за пакетний запит. Ефективніше, ніж виклик send() в петлі, і зменшує ризик влучення в обмеження швидкості для високооб’ємного надсилання.

• Приклад: « Використовувати пакетну відправку для щотижневих коротких листів — виклик send() у петлі для 10 000 користувачів призведе до обмеження швидкості, але відсилання пакетами по 100 буде набагато надійнішим. » *

Импотенция Властивість, за допомогою якої надіслання одного і того ж запиту декілька разів дасть такий самий результат без дублювання побічних ефектів — у цьому випадку, без надсилання дублікатів листів електронної пошти. Перенаправлення підтримує ключі з ідентичністю: якщо ви двічі надсилаєте один і той самий ключ, другий запит поверне результат першого без надсилання іншої електронної пошти.

• Приклад: « Передавати ключ ідемпотенції під час надсилання листа для скасування пароля — якщо користувач двічі клацне кнопку і буде випущено два запити, ключ ідемпотенції забезпечить отримання користувачем лише одного листа. » *

Як використовувати цей словник

Обговорення надійності електронної пошти зосереджені на трьох речах: перевірка домену (чи можемо ми взагалі відправляти?), доставляння (чи потрапляють наші листи у скриньки?) і відстеження подій (чи ми обробляємо відмови і скарги?). Команди використовують події webhook для закриття циклу зворотнього зв’язку — оновлення записів бази даних, коли електронні листи відкидаються, і придушення майбутніх відправлень на неправильні адреси.

React Email з’являється в обговореннях дизайну і перегляду коду. Інженери обговорюють структуру компонентів, як передати динамічні дані до шаблонів, і як переглянути електронні листи під час розробки. Ключова перевага — уникнення необробленої розмітки таблиці HTML — є поширеною темою для обговорення при обґрунтуванні залежності.

Приклад розмови

Зара: Електронні листи про скасування пароля не надходять. На панелі перенаправлення показано, що вони надіслані. ** Felix: ** Перевірте, чи завершено перевірку домену — from адреси у неперевірених доменах іноді відкидаються без повідомлення. ** Zara: ** Домен, здається, перевірений. Ми працюємо з email.bounced webhook? Может, адреса в списке подавления. Хороший аргумент. Перевірте список пригнічення на панелі Перенадіслати — якщо адреса вже була відхилена раніше, програма автоматично заблокує майбутні надсилання на цю адресу за допомогою пункту Перенадіслати.

Practice

1. Налаштувати перенаправлення у тестовому проекті, перевірити домен і надіслати тестову електронну пошту за допомогою методу send(). Записуйте кожен крок англійською мовою, називаючи кожне поле, яке ви налаштовуєте, і пояснюючи, чому.
2. Створення обробника webhook для подій email.bounced. Опишете англійською мовою, що має робити ваш код, коли він отримує жорсткий відскок проти м’ якого відскоку — які поля бази даних ви оновлюєте і чому?
3. Поясніть ідемпотентність нетехнічним товаришам по команді, використовуючи реальну аналогію (наприклад, натискання кнопки закриття дверей в ліфті кілька разів). Потім відобразити аналогію знову у випадку використання ключа імпотентності електронної пошти.

На практиці: Навігація зворотного зв’язку і співпраці навколо ідемпотенції

Будьмо чесними - коли ви будуєте системи, які займаються асинхронними завданнями, такими як надсилання електронних листів, термінологія може відчуватися… щільною. Ви дізналися про send(), batch send, і навіть трохи залякав концепцію ідемпотентності. Але розуміння того, як ефективно передати ці ідеї, так само важливо, як і знати самі визначення. Недостатньо просто сказати, що функція повинна бути idempotent; вам потрібно передати, чому це важливо, і як її реалізація впливає на ваших колег.

Розглянемо такий сценарій: Сара, старший інженер команди, переглядає запит на збирання нової можливості за допомогою бібліотеки Resend. У описі PR написано: « Впроваджено пакетне надсилання для покращення швидкості доставки електронної пошти ». Коментар Сари: « Це виглядає добре, але чи можете ви додати документацію, яка пояснює, чому краще використовувати пакетне надсилання? » Я особливо турбуюся про ідемпотенцію — нам потрібно переконатися, що якщо електронна пошта зазнає невдачі і спробується знову, вона не буде відправлена декілька разів. Чи можете ви включити механізм для відстеження ідентифікацій повідомлень?» Це не просто технічне запитання; це запит на пояснення і невеликий крок у напрямку найкращих практик. Ключовим тут є обговорення навколо * зменшення ризику * - запобігання дублювання електронної пошти через потенційні помилки. Він уникає жаргону, безпосередньо звертаючись до наслідків не розглядання ідемпотентності: марні ресурси і потенційно заплутані отримувачі. Крім того, фрази на кшталт «механізм для відстеження ідентифікаторів повідомлень» є більш доступними, ніж просто заява «реалізувати ідемпотентність»

Інша поширена ситуація виникає в розмовах Slack при зневадженні проблем з доставкою електронної пошти. Припустимо, що розробник повідомляє: «Електронна пошта не надходить! Я використовував метод send() на компоненті React Email.” Додаткова корисна відповідь від іншого інженера може бути: “Гаразд, давайте розслідуємо. Чи можете ви підтвердити, що ви реалізували логіку повторення? Нам потрібно переконатися, що якщо доставка не вдається - що може статися через тимчасові проблеми з мережею - ми не намагаємося кілька разів відправити ту ж саму електронну пошту. Функція idempotency програми Resend розроблена для цього, але вона залежить від унікальних ідентифікаторів повідомлень. » Цей підхід підкреслює * чому * за технічною реалізацією і тонко нагадує репортеру про основний принцип.

Нарешті, при написанні описів PR, чіткість є найважливішою. Замість простого опису « Використання пакетного надсилання », ефективнішим буде опис: « Реалізовано пакетне надсилання для оптимізації швидкодії доставки електронної пошти, зберігаючи при цьому ідентичність за допомогою унікальних ідентифікаторів повідомлень, створених за допомогою пункту Перенадіслати ». Таким чином, буде поєднано ефективність з важливим аспектом запобігання дублікатів, що показує глибше розуміння роботи системи.

# Example using Resend CLI to verify idempotency (demonstrating ID generation)
resend --url https://api.resend.com/v3 --key YOUR_RESEND_API_KEY list

За допомогою цієї команди можна побачити, як програма Перенадіслати автоматично створює унікальні ідентифікатори повідомлень, що є ключовим елементом гарантії ідентичності повідомлень. У виводі буде показано ці ідентифікатори, що є ключовим для підтвердження того, що кожна електронна пошта розглядається як окрема і запобігає дублюванню.