با استفاده از پسوند Trigger Email

پسوند Trigger Email ( firestore-send-email ) به شما امکان می دهد به طور خودکار ایمیل ها را بر اساس اسناد موجود در مجموعه Cloud Firestore ارسال کنید. افزودن یک سند به مجموعه، این برنامه افزودنی را برای ارسال ایمیل ساخته شده از فیلدهای سند فعال می کند. فیلدهای سطح بالای سند، فرستنده و گیرندگان ایمیل، از جمله گزینه‌های to , cc و bcc را مشخص می‌کنند (هر کدام UID پشتیبانی می‌کنند). فیلد message سند سایر عناصر ایمیل مانند خط موضوع و متن ایمیل (چه متن ساده یا HTML) را مشخص می کند.

در اینجا یک سند اساسی برای نوشتن است که این پسوند را فعال می کند:

admin.firestore().collection('mail').add({
  to: 'someone@example.com',
  message: {
    subject: 'Hello from Firebase!',
    html: 'This is an <code>HTML</code> email body.',
  },
})

همچنین می توانید به صورت اختیاری این برنامه افزودنی را برای نمایش ایمیل ها با استفاده از قالب های Handlebars پیکربندی کنید.

تنظیم قبل از نصب

قبل از نصب افزونه، مراحل زیر را انجام دهید:

  1. سرویس ایمیل خروجی خود را تنظیم کنید.

    هنگامی که برنامه افزودنی Trigger Email را نصب می کنید، باید جزئیات اتصال و احراز هویت یک سرور SMTP را مشخص کنید، که برنامه افزودنی از آن برای ارسال ایمیل استفاده می کند. این معمولاً توسط یک سرویس تحویل ایمیل مانند Sendgrid، Mailgun یا Mailchimp Transactional Email ارائه می‌شود، اما می‌تواند سروری باشد که خودتان آن را اجرا می‌کنید.

  2. یک مجموعه اسناد ایمیل ایجاد کنید.

    برنامه افزودنی Trigger Email به اسناد جدید در مجموعه Cloud Firestore که شما مشخص کرده اید گوش می دهد. هنگامی که یک سند جدید پیدا می کند، برنامه افزودنی یک ایمیل بر اساس فیلدهای سند ارسال می کند. برای این منظور می توانید از هر مجموعه Cloud Firestore استفاده کنید. نمونه های موجود در این صفحه از مجموعه ای به نام email استفاده می کنند.

  3. قوانین امنیتی را برای مجموعه اسناد ایمیل خود تنظیم کنید.

    این برنامه افزودنی می تواند برای راه اندازی تحویل ایمیل به طور مستقیم از برنامه های مشتری استفاده شود. با این حال، برای جلوگیری از سوء استفاده احتمالی، باید دسترسی مشتری به مجموعه را به دقت کنترل کنید (شما نمی خواهید کاربران بتوانند ایمیل های دلخواه را از آدرس شرکت شما ارسال کنند!).

    قوانین امنیتی از برنامه‌ای به برنامه دیگر متفاوت است، اما همیشه باید مطمئن شوید که ایمیل‌ها فقط برای گیرندگان مورد نظر ارسال می‌شوند و محتوای آزاد به حداقل می‌رسد. الگوها می‌توانند در اینجا کمک کنند—شما می‌توانید از قوانین امنیتی استفاده کنید تا بررسی کنید که داده‌هایی که در قالب جمع‌شده است مطابق با انتظارات شما از آنچه کاربر باید اجازه راه‌اندازی داشته باشد، مطابقت دارد.

  4. اختیاری: مجموعه کاربران را تنظیم کنید.

    در استفاده اولیه از این برنامه افزودنی، شما گیرندگان ایمیل را با مشخص کردن آدرس ایمیل آنها در فیلدهای to ، cc و bcc سند پیام مشخص می‌کنید. به عنوان جایگزین، اگر یک پایگاه داده کاربر در Cloud Firestore دارید، می توانید گیرندگان را با استفاده از UID کاربران مشخص کنید. برای این کار، مجموعه کاربران شما باید این معیارها را داشته باشد:

    • مجموعه باید روی شناسه های کاربری کلید شود. یعنی شناسه سند هر سند کاربری در مجموعه باید Firebase Authentication UID کاربر باشد.
    • هر سند کاربر باید دارای یک فیلد email حاوی آدرس ایمیل کاربر باشد.

  5. اختیاری: مجموعه الگوها را تنظیم کنید.

    می توانید ایمیل ها را با استفاده از قالب های Handlebars رندر کنید. برای انجام این کار، به یک مجموعه Cloud Firestore نیاز دارید که حاوی الگوهای شما باشد.

    برای جزئیات بیشتر به استفاده از الگوهای Handlebars با پسوند Trigger Email مراجعه کنید.

افزونه را نصب کنید

برای نصب برنامه افزودنی، مراحل موجود در صفحه Install a Firebase Extension را دنبال کنید. به طور خلاصه یکی از موارد زیر را انجام دهید:

  • کنسول Firebase : روی دکمه زیر کلیک کنید:

    افزونه Trigger Email را نصب کنید

  • CLI: دستور زیر را اجرا کنید:

    firebase ext:install firebase/firestore-send-email --project=projectId-or-alias

هنگامی که برنامه افزودنی را نصب می کنید، از شما خواسته می شود که اطلاعات اتصال SMTP و مجموعه های Cloud Firestore را که قبلاً تنظیم کرده اید، مشخص کنید.

از پسوند استفاده کنید

پس از نصب، این برنامه افزودنی تمام نوشته‌های سند در مجموعه‌ای که پیکربندی کرده‌اید را نظارت می‌کند. ایمیل بر اساس محتویات فیلدهای سند تحویل داده می شود. فیلدهای سطح بالا فرستنده و گیرنده ایمیل را مشخص می کنند. فیلد message حاوی جزئیات ایمیل برای تحویل، از جمله متن ایمیل است.

مثال: ارسال یک ایمیل

برای ارسال یک پیام ساده، یک سند با یک فیلد to و یک فیلد message با محتوای زیر به مجموعه پیام‌های خود اضافه کنید:

to: ['someone@example.com'],
message: {
  subject: 'Hello from Firebase!',
  text: 'This is the plaintext section of the email body.',
  html: 'This is the <code>HTML</code> section of the email body.',
}

فیلدهای فرستنده و گیرنده

فیلدهای سطح بالای سند اطلاعات فرستنده و گیرنده ایمیل را ارائه می دهند. فیلدهای موجود عبارتند از:

  • از: آدرس ایمیل فرستنده. اگر در سند مشخص نشده باشد، از پارامتر "Default FROM address" پیکربندی شده استفاده می کند.
  • replyTo: آدرس ایمیل پاسخ به. اگر در سند مشخص نشده باشد، از پارامتر پیکربندی شده "Default REPLY-TO address" استفاده می کند.
  • به: یک آدرس ایمیل گیرنده یا یک آرایه حاوی چندین آدرس ایمیل گیرنده.
  • toUids: آرایه ای حاوی UIDهای گیرنده.
  • cc: یک آدرس ایمیل گیرنده یا یک آرایه حاوی چندین آدرس ایمیل گیرنده.
  • ccUids: آرایه ای حاوی UIDهای گیرنده CC.
  • bcc: یک آدرس ایمیل گیرنده یا یک آرایه حاوی چندین آدرس ایمیل گیرنده.
  • bccUids: آرایه ای حاوی UIDهای گیرنده BCC.
  • headers: یک شی از فیلدهای هدر اضافی (به عنوان مثال، {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"} ).

توجه: گزینه‌های toUids ، ccUids ، و bccUids ایمیل‌ها را بر اساس UIDهای کاربر که روی آدرس‌های ایمیل در یک سند Cloud Firestore کلید شده‌اند، تحویل می‌دهند. برای استفاده از این گزینه‌های گیرنده، باید یک مجموعه Cloud Firestore برای پارامتر «مجموعه کاربران» برنامه افزودنی مشخص کنید. سپس برنامه افزودنی می تواند فیلد email را برای هر UID مشخص شده در فیلدهای toUids ، ccUids و/یا bccUids بخواند.

فیلد پیام

فیلد message سند حاوی اطلاعات تحویل خام برای ایمیل است. این فیلد معمولاً فقط باید با کدهای قابل اعتمادی که در سرورهای خود یا توابع ابری شما اجرا می شود پر شود (به بخش "قوانین امنیتی و ارسال ایمیل" در زیر مراجعه کنید).

ویژگی های موجود برای فیلد message عبارتند از:

  • messageId: سرصفحه شناسه پیام برای ایمیل، در صورت وجود.
  • موضوع: موضوع ایمیل.
  • text: محتوای متن ساده ایمیل.
  • html: محتوای HTML ایمیل.
  • amp: محتوای AMP4EMAIL ایمیل.
  • پیوست ها: آرایه ای حاوی پیوست(های)؛ گزینه‌های Nodemailer پشتیبانی می‌شوند: رشته utf-8، نوع محتوای سفارشی، URL، رشته رمزگذاری‌شده، URI داده و گره MIME از پیش تولید شده (دقت داشته باشید که ایمیل شما به سیستم فایل سرور ابری دسترسی ندارد).

استفاده پیشرفته

با استفاده پیشرفته تر از این افزونه آشنا شوید: