이메일 트리거 확장 프로그램 사용
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
이메일 트리거 확장 프로그램(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 템플릿을 사용하여 이메일을 렌더링하도록 이 확장 프로그램을 구성할 수도 있습니다.
설치 전 설정
확장 프로그램을 설치하기 전에 다음 단계를 완료하세요.
발신 메일 서비스를 설정합니다.
이메일 트리거 확장 프로그램을 설치할 때 확장 프로그램이 이메일을 보내는 데 사용하는 SMTP 서버의 연결 및 인증 세부정보를 지정해야 합니다. 이는 일반적으로 SendGrid, Mailgun 또는 Mailchimp Transactional Email과 같은 이메일 전송 서비스에서 제공되지만, 사용자가 직접 실행하는 서버일 수도 있습니다.
이메일 문서 컬렉션을 만듭니다.
이메일 트리거 확장 프로그램은 사용자가 지정한 Cloud Firestore 컬렉션에서 새 문서를 수신 대기합니다. 새 문서를 찾으면 확장 프로그램이 문서의 필드를 기준으로 이메일을 보냅니다. 모든 Cloud Firestore 컬렉션은 이러한 용도로 사용할 수 있습니다. 본 페이지의 예시에서는 email이라는 컬렉션을 사용합니다.
이메일 문서 컬렉션에 대한 보안 규칙을 설정합니다.
이 확장 프로그램을 사용하면 클라이언트 애플리케이션에서 직접 이메일 전송을 트리거할 수 있습니다. 그러나 사용자가 회사 주소로 임의의 이메일을 전송하는 잠재적인 악용을 방지하려면 컬렉션에 대한 클라이언트 액세스를 주의해서 제어해야 합니다.
보안 규칙은 애플리케이션에 따라 달라지지만 의도한 수신자에게만 이메일이 전송되고 자유 형식 콘텐츠가 최소 수준으로 유지되도록 항상 주의해야 합니다. 이 경우 템플릿이 도움이 될 수 있습니다. 보안 규칙을 사용하면 템플릿에 채워지는 데이터가 사용자의 트리거가 허용되는 예상 대상과 일치하는지 확인할 수 있습니다.
선택사항: 사용자 컬렉션을 설정합니다.
이 확장 프로그램의 기본적인 사용법에 따라 메시지 문서의 to, cc, bcc 필드에 이메일 주소를 지정하여 이메일 수신자를 지정합니다. 또는 Cloud Firestore에 사용자 데이터베이스가 있는 경우 사용자의 UID를 사용하여 수신자를 지정할 수 있습니다. 이 작업을 수행하려면 사용자 컬렉션이 다음 기준을 충족해야 합니다.
- 컬렉션에는 사용자 ID에 키가 지정되어야 합니다. 즉, 컬렉션에 있는 각 사용자 문서의 문서 ID는 사용자의 Firebase Authentication UID여야 합니다.
- 각 사용자 문서에는 사용자의 이메일 주소를 포함하는
email 필드가 있어야 합니다.
선택사항: 템플릿 컬렉션을 설정합니다.
Handlebars 템플릿을 사용하여 이메일을 렌더링할 수 있습니다.
이렇게 하려면 템플릿을 포함할 Cloud Firestore 컬렉션이 필요합니다.
자세한 내용은 이메일 트리거 확장 프로그램으로 Handlebars 템플릿 사용을 참조하세요.
확장 프로그램 설치
확장 프로그램을 설치하려면 Firebase Extension 설치 페이지의 단계를 따르세요. 요약하면 다음 중 하나를 수행합니다.
확장 프로그램을 설치할 때 이전에 설정한 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: 답장할 이메일 주소입니다. 문서에 지정되지 않은 경우 구성된 '기본 답장받을 주소' 파라미터를 사용합니다.
- to: 단일의 수신자 이메일 주소 또는 다수의 수신자 이메일 주소가 포함된 배열입니다.
- toUids: 수신자 UID가 포함된 배열입니다.
- cc: 단일의 수신자 이메일 주소 또는 다수의 수신자 이메일 주소가 포함된 배열입니다.
- ccUids: 참조 수신자 UID가 포함된 배열입니다.
- bcc: 단일의 수신자 이메일 주소 또는 다수의 수신자 이메일 주소가 포함된 배열입니다.
- bccUids: 숨은참조 수신자 UID가 포함된 배열입니다.
- headers: 추가 헤더 필드의 객체입니다(예:
{"X-Custom-Header": "value", "X-Second-Custom-Header": "value"}).
참고: toUids, ccUids, bccUids 옵션은 Cloud Firestore 문서 내의 이메일 주소로 키가 지정된 사용자 UID를 기반으로 이메일을 전송합니다. 이러한 수신자 옵션을 사용하려면 확장 프로그램의 '사용자 컬렉션' 파라미터에 대한 Cloud Firestore 컬렉션을 지정해야 합니다. 이제 확장 프로그램에서 toUids, ccUids 또는 bccUids 필드에 지정된 각 UID에 대한 email 필드를 읽을 수 있습니다.
메시지 필드
문서의 message 필드에는 이메일의 원시 전송 정보가 포함됩니다. 이 필드는 일반적으로 자체 서버 또는 Cloud Functions에서 실행하는 신뢰할 수 있는 코드로만 채워져야 합니다(아래의 '보안 규칙 및 이메일 전송' 섹션 참조).
message 필드에 사용 가능한 속성은 다음과 같습니다.
- messageId: 이메일의 메시지 ID 헤더입니다(있는 경우).
- subject: 이메일의 제목입니다.
- text: 이메일의 일반 텍스트 콘텐츠입니다.
- html: 이메일의 HTML 콘텐츠입니다.
- amp: 이메일의 AMP4EMAIL 콘텐츠입니다.
- attachments: 첨부파일을 포함하는 배열입니다. 지원되는 Nodemailer 옵션에는 utf-8 문자열, 커스텀 콘텐츠 유형, URL, 인코딩된 문자열, 데이터 URI, 사전 생성된 MIME 노드가 있습니다(이메일은 클라우드 서버의 파일 시스템에 액세스할 수 없음).
고급 사용
이 확장 프로그램의 고급 사용에 대해 자세히 알아보세요.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-12(UTC)
[null,null,["최종 업데이트: 2025-08-12(UTC)"],[],[],null,["# Using the Trigger Email extension\n\n\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----------------------\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---------------------\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-----------------\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\n### Example: 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\n### Sender 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\n### Message 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------------\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)"]]
