با مجموعه‌ها، منظم بمانید
ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
پسوند 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 پیکربندی کنید.
تنظیم قبل از نصب
قبل از نصب افزونه، مراحل زیر را انجام دهید:
سرویس ایمیل خروجی خود را تنظیم کنید.
هنگامی که برنامه افزودنی Trigger Email را نصب می کنید، باید جزئیات اتصال و احراز هویت یک سرور SMTP را مشخص کنید، که برنامه افزودنی از آن برای ارسال ایمیل استفاده می کند. این معمولاً توسط یک سرویس تحویل ایمیل مانند Sendgrid، Mailgun یا Mailchimp Transactional Email ارائه می‌شود، اما می‌تواند سروری باشد که خودتان آن را اجرا می‌کنید.
یک مجموعه اسناد ایمیل ایجاد کنید.
برنامه افزودنی Trigger Email به اسناد جدید در مجموعه Cloud Firestore که شما مشخص کرده اید گوش می دهد. هنگامی که یک سند جدید پیدا می کند، برنامه افزودنی یک ایمیل بر اساس فیلدهای سند ارسال می کند. برای این منظور می توانید از هر مجموعه Cloud Firestore استفاده کنید. نمونه های موجود در این صفحه از مجموعه ای به نام email استفاده می کنند.
قوانین امنیتی را برای مجموعه اسناد ایمیل خود تنظیم کنید.
این برنامه افزودنی می تواند برای راه اندازی تحویل ایمیل به طور مستقیم از برنامه های مشتری استفاده شود. با این حال، برای جلوگیری از سوء استفاده احتمالی، باید دسترسی مشتری به مجموعه را به دقت کنترل کنید (شما نمی خواهید کاربران بتوانند ایمیل های دلخواه را از آدرس شرکت شما ارسال کنند!).
قوانین امنیتی از برنامه‌ای به برنامه دیگر متفاوت است، اما همیشه باید مطمئن شوید که ایمیل‌ها فقط برای گیرندگان مورد نظر ارسال می‌شوند و محتوای آزاد به حداقل می‌رسد. الگوها می‌توانند در اینجا کمک کنند—شما می‌توانید از قوانین امنیتی استفاده کنید تا بررسی کنید که داده‌هایی که در قالب جمع‌شده است مطابق با انتظارات شما از آنچه کاربر باید اجازه راه‌اندازی داشته باشد، مطابقت دارد.
اختیاری: مجموعه کاربران را تنظیم کنید.
در استفاده اولیه از این برنامه افزودنی، شما گیرندگان ایمیل را با مشخص کردن آدرس ایمیل آنها در فیلدهای to ، cc و bcc سند پیام مشخص می‌کنید. به عنوان جایگزین، اگر یک پایگاه داده کاربر در Cloud Firestore دارید، می توانید گیرندگان را با استفاده از UID کاربران مشخص کنید. برای این کار، مجموعه کاربران شما باید این معیارها را داشته باشد:
مجموعه باید روی شناسه های کاربری کلید شود. یعنی شناسه سند هر سند کاربری در مجموعه باید Firebase Authentication UID کاربر باشد.
هر سند کاربر باید دارای یک فیلد email حاوی آدرس ایمیل کاربر باشد.
اختیاری: مجموعه الگوها را تنظیم کنید.
می توانید ایمیل ها را با استفاده از قالب های Handlebars رندر کنید. برای انجام این کار، به یک مجموعه Cloud Firestore نیاز دارید که حاوی الگوهای شما باشد.
هنگامی که برنامه افزودنی را نصب می کنید، از شما خواسته می شود که اطلاعات اتصال 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: سرصفحه شناسه پیام برای ایمیل، در صورت وجود.
پیوست ها: آرایه ای حاوی پیوست(های)؛ گزینه‌های Nodemailer پشتیبانی می‌شوند: رشته utf-8، نوع محتوای سفارشی، URL، رشته رمزگذاری‌شده، URI داده و گره MIME از پیش تولید شده (دقت داشته باشید که ایمیل شما به سیستم فایل سرور ابری دسترسی ندارد).
تاریخ آخرین بهروزرسانی 2025-07-25 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین بهروزرسانی 2025-07-25 بهوقت ساعت هماهنگ جهانی."],[],[],null,["\u003cbr /\u003e\n\nThe Trigger Email extension (`firestore-send-email`) lets you automatically send\nemails based on documents in a Cloud Firestore collection. Adding a document to\nthe collection triggers this extension to send an email built from the\ndocument's fields. The document's top-level fields specify the email sender and\nrecipients, including `to`, `cc`, and `bcc` options (each supporting UIDs). The\ndocument's `message` field specifies the other email elements, like subject line\nand email body (either plaintext or HTML).\n\nHere's a basic example document write that would trigger this extension: \n\n admin.firestore().collection('mail').add({\n to: 'someone@example.com',\n message: {\n subject: 'Hello from Firebase!',\n html: 'This is an \u003ccode\u003eHTML\u003c/code\u003e email body.',\n },\n })\n\nYou can also optionally configure this extension to render emails using\n[Handlebars](/docs/extensions/official/firestore-send-email/templates) templates.\n\nPre-installation setup\n\nBefore you install the extension, complete these steps:\n\n1. Set up your outgoing mail service.\n\n When you install the Trigger Email extension, you will need to specify the\n connection and authentication details of an SMTP server, which the extension\n uses to send emails. This is typically provided by an email delivery service\n such as Sendgrid, Mailgun, or Mailchimp Transactional Email, but it could\n also be a server you run yourself.\n2. Create an email documents collection.\n\n The Trigger Email extension listens for new documents in a Cloud Firestore\n collection that you specify. When it finds a new document, the extension\n sends an email based on the document's fields. You can use any Cloud Firestore\n collection for this purpose; the examples on this page use a collection\n named `email`.\n3. Set up security rules for your email documents collection.\n\n This extension can be used to trigger email delivery directly from client\n applications. However, you should carefully control client access to the\n collection to avoid potential abuse (you don't want users able to send\n arbitrary emails from your company's address!).\n\n Security rules will vary from application to application, but you should\n always make sure that emails are sent only to intended recipients and\n free-form content is kept to a minimum. Templates can help here---you\n can use security rules to verify that the data being populated to the\n template matches your expectations for what a user should be allowed to\n trigger.\n4. Optional: Set up a users collection.\n\n Under basic usage of this extension, you specify the recipients of an email\n by specifying their email addresses in the `to`, `cc`, and `bcc` fields of\n the message document. As an alternative, if you have a user database in\n Cloud Firestore, you can specify recipients using the users' UIDs. For this\n to work, your users collection must meet these criteria:\n - The collection must be keyed on user IDs. That is, the document ID of each user document in the collection must be the user's Firebase Authentication UID.\n - Each user document must have an `email` field containing the user's email address.\n5. Optional: Set up a templates collection.\n\n You can render emails using [Handlebars templates](https://handlebarsjs.com/).\n To do so, you will need a Cloud Firestore collection to contain your\n templates.\n\n See [Use Handlebars templates with the Trigger Email extension](/docs/extensions/official/firestore-send-email/templates)\n for details.\n\nInstall the extension\n\nTo install the extension, follow the steps on the\n[Install a Firebase Extension](/docs/extensions/install-extensions)\npage. In summary, do one of the following:\n\n- **Firebase console:** Click the following button:\n\n [Install the Trigger Email extension](https://console.firebase.google.com/project/_/extensions/install?ref=firebase/firestore-send-email)\n- **CLI:** Run the following command:\n\n ```\n firebase ext:install firebase/firestore-send-email --project=projectId-or-alias\n ```\n\n \u003cbr /\u003e\n\nWhen you install the extension, you will be prompted to specify your SMTP\nconnection information and the Cloud Firestore collections you set up earlier.\n\nUse the extension\n\nAfter installation, this extension monitors all document writes to the\ncollection you configured. Email is delivered based on the contents of the\ndocument's fields. The top-level fields specify the email's sender and\nrecipients. The `message` field contains the details of the email to deliver,\nincluding the email body.\n\nExample: Send an email\n\nTo send a simple message, add a document to your messages collection with a `to`\nfield and a `message` field with the following content: \n\n to: ['someone@example.com'],\n message: {\n subject: 'Hello from Firebase!',\n text: 'This is the plaintext section of the email body.',\n html: 'This is the \u003ccode\u003eHTML\u003c/code\u003e section of the email body.',\n }\n\nSender and recipient fields\n\nThe top-level fields of the document supply the email sender and recipient\ninformation. Available fields are:\n\n- **from:** The sender's email address. If not specified in the document, uses the configured \"Default FROM address\" parameter.\n- **replyTo:** The reply-to email address. If not specified in the document, uses the configured \"Default REPLY-TO address\" parameter.\n- **to:** A single recipient email address or an array containing multiple recipient email addresses.\n- **toUids:** An array containing the recipient UIDs.\n- **cc:** A single recipient email address or an array containing multiple recipient email addresses.\n- **ccUids:** An array containing the CC recipient UIDs.\n- **bcc:** A single recipient email address or an array containing multiple recipient email addresses.\n- **bccUids:** An array containing the BCC recipient UIDs.\n- **headers:** An object of additional header fields (for example, `{\"X-Custom-Header\": \"value\", \"X-Second-Custom-Header\": \"value\"}`).\n\n**NOTE:** The `toUids`, `ccUids`, and `bccUids` options deliver emails based on\nuser UIDs keyed to email addresses within a Cloud Firestore document. To use\nthese recipient options, you need to specify a Cloud Firestore collection for\nthe extension's \"Users collection\" parameter. The extension can then read the\n`email` field for each UID specified in the `toUids`, `ccUids`, and/or `bccUids` fields.\n\nMessage field\n\nThe `message` field of the document contains raw delivery information for the\nemail. This field should generally only be populated by trusted code running in\nyour own servers or Cloud Functions (refer to the \"Security rules and sending\nemail\" section below).\n\nAvailable properties for the `message` field are:\n\n- **messageId:** A message ID header for the email, if any.\n- **subject:** The subject of the email.\n- **text:** The plaintext content of the email.\n- **html:** The HTML content of the email.\n- **amp:** The [AMP4EMAIL](https://amp.dev/documentation/guides-and-tutorials/learn/email-spec/amp-email-format/) content of the email.\n- **attachments:** An array containing attachment(s); [Nodemailer options](https://nodemailer.com/message/attachments/) supported: utf-8 string, custom content type, URL, encoded string, data URI, and pregenerated MIME node (be aware that your email has no access to the cloud server's file system).\n\nAdvanced use\n\nLearn about more advanced use of this extension:\n\n- [Use Handlebars templates with the Trigger Email extension](/docs/extensions/official/firestore-send-email/templates)\n- [Manage delivery status with the Trigger Email extension](/docs/extensions/official/firestore-send-email/delivery-status)"]]
