تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
يتيح لك إضافة 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، ولكن يمكن أن يكون أيضًا خادمًا تديره بنفسك.
إنشاء مجموعة مستندات للرسائل الإلكترونية
تستمع إضافة "إرسال رسالة إلكترونية عند تشغيل حدث" إلى المستندات الجديدة في Cloud FirestoreمجموعةCloud Firestore تحدّدها. عندما تعثر الإضافة على مستند جديد، ترسل رسالة إلكترونية استنادًا إلى حقول المستند. يمكنك استخدام أي مجموعة Cloud Firestore لهذا الغرض، وتستخدِم الأمثلة الواردة في هذه الصفحة مجموعة باسم email.
إعداد قواعد الأمان لمجموعة مستندات البريد الإلكتروني
يمكن استخدام هذه الإضافة لتفعيل عملية تسليم الرسائل الإلكترونية مباشرةً من تطبيقات العميل. ومع ذلك، عليك التحكّم بعناية في وصول العملاء إلى المجموعة لتجنُّب أي إساءة استخدام محتملة (لا تريد أن يتمكّن المستخدمون من إرسال رسائل إلكترونية عشوائية من عنوان شركتك).
تختلف قواعد الأمان من تطبيق إلى آخر، ولكن عليك دائمًا التأكّد من أنّ الرسائل الإلكترونية يتم إرسالها فقط إلى المستلمين المقصودين، وأنّ المحتوى الحر يتم إبقاؤه في الحد الأدنى. يمكن أن تساعد النماذج في ذلك، إذ يمكنك استخدام قواعد الأمان للتحقّق من أنّ البيانات التي يتم ملؤها في النموذج تتطابق مع توقعاتك بشأن ما يجب السماح للمستخدم بتشغيله.
اختياري: إعداد مجموعة مستخدمين
ضمن الاستخدام الأساسي لهذه الإضافة، يمكنك تحديد مستلمي رسالة إلكترونية
من خلال تحديد عناوين بريدهم الإلكتروني في الحقول to وcc وbcc
في مستند الرسالة. كحلّ بديل، إذا كان لديك قاعدة بيانات مستخدمين في Cloud Firestore، يمكنك تحديد المستلِمين باستخدام أرقام التعريف الفريدة للمستخدمين. لكي تنجح هذه العملية، يجب أن تستوفي مجموعة المستخدمين المعايير التالية:
يجب أن تستند عملية الجمع إلى أرقام تعريف المستخدمين. أي أنّ معرّف المستند لكل مستند مستخدم في المجموعة يجب أن يكون Firebase Authenticationمعرّف المستخدم الفريد.
يجب أن يتضمّن مستند كل مستخدم الحقل 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.',}
حقول المُرسِل والمستلِم
توفّر الحقول ذات المستوى الأعلى في المستند معلومات عن مُرسِل الرسالة الإلكترونية ومُستلِمها. الحقول المتاحة هي:
من: عنوان البريد الإلكتروني للمُرسِل في حال عدم تحديدها في المستند، يتم استخدام المَعلمة "عنوان FROM التلقائي" التي تم ضبطها.
replyTo: عنوان البريد الإلكتروني للردّ في حال عدم تحديدها في المستند، يتم استخدام المَعلمة "عنوان REPLY-TO التلقائي" التي تم ضبطها.
إلى: عنوان بريد إلكتروني واحد للمستلِم أو مصفوفة تحتوي على عدة عناوين بريد إلكتروني للمستلِمين
toUids: مصفوفة تحتوي على المعرّفات الفريدة للمستلِمين.
cc: عنوان بريد إلكتروني لمستلِم واحد أو مصفوفة تحتوي على عناوين بريد إلكتروني لعدة مستلمين
ccUids: مصفوفة تحتوي على معرّفات المستخدمين الفريدة للمستلمين في الحقل "نسخة إلى".
نسخة مخفية الوجهة: عنوان بريد إلكتروني لمستلم واحد أو مصفوفة تحتوي على عناوين بريد إلكتروني لعدة مستلمين
bccUids: مصفوفة تحتوي على معرّفات المستخدمين الفريدة لمستلمي النسخة المخفية الوجهة.
headers: كائن يتضمّن حقول رؤوس إضافية (على سبيل المثال، {"X-Custom-Header": "value", "X-Second-Custom-Header": "value"}).
ملاحظة: تقدّم الخيارات toUids وccUids وbccUids رسائل إلكترونية استنادًا إلى معرّفات المستخدمين الفريدة المرتبطة بعناوين البريد الإلكتروني ضِمن مستند Cloud Firestore. لاستخدام خيارات المستلِمين هذه، عليك تحديد مجموعة Cloud Firestore لمعلَمة "مجموعة المستخدمين" الخاصة بالإضافة. يمكن للإضافة بعد ذلك قراءة الحقل email لكل معرّف فريد محدّد في الحقول toUids و/أو ccUids و/أو bccUids.
حقل الرسالة
يحتوي الحقل message في المستند على معلومات التسليم الأولية للرسالة الإلكترونية. يجب بشكل عام أن يملأ هذا الحقل رمز موثوق به فقط يتم تشغيله على خوادمك أو في Cloud Functions (يُرجى الرجوع إلى قسم "قواعد الأمان وإرسال الرسائل الإلكترونية" أدناه).
السمات المتاحة للحقل message هي:
messageId: عنوان معرّف الرسالة للبريد الإلكتروني، إذا كان متوفّرًا.
تاريخ التعديل الأخير: 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)"]]
