> ## Documentation Index
> Fetch the complete documentation index at: https://chatbotx.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Kết nối Email vào ChatbotX

Tính năng Email cho phép bạn biến bất kỳ địa chỉ email nào thành hộp thư đến của ChatbotX. Email đến sẽ được hiển thị dưới dạng hội thoại, và nhóm của bạn có thể trả lời trực tiếp từ ChatbotX bằng kết nối SMTP để gửi thông báo, xác nhận đơn hàng, tài liệu hoặc chuỗi email chăm sóc khách hàng tự động.

<Warning>
  **Lưu ý quan trọng về khả năng gửi Email (Deliverability):**\
  Để đảm bảo email của bạn không bị đánh dấu là thư rác (Spam) và tỷ lệ gửi thành công cao nhất, hãy chắc chắn rằng bạn đã cấu hình xác thực tên miền (**SPF**, **DKIM**, và **DMARC**) trong trình quản lý DNS của tên miền gửi đi trước khi sử dụng ở môi trường thực tế (production).
</Warning>

<Info>
  Nếu bạn chưa có nhà cung cấp SMTP riêng, hãy xem [hướng dẫn cấu hình Email](/configuration/emails) để biết các nhà cung cấp được đề xuất và ví dụ về chuỗi kết nối.
</Info>

Dưới đây là hướng dẫn từ cơ bản đến nâng cao để thiết lập và sử dụng tính năng gửi Email trong ChatbotX.

## Bước 1: Lấy thông tin xác thực SMTP từ nhà cung cấp

Tùy thuộc vào nhà cung cấp dịch vụ Email bạn đang sử dụng, bạn sẽ cần các thông tin cơ bản sau để kết nối với ChatbotX:

* **SMTP Host/Server**
* **SMTP Port** (Thường là `465` cho SSL hoặc `587` cho TLS)
* **SMTP Username** (Thường là địa chỉ email của bạn)
* **SMTP Password** (Mật khẩu ứng dụng hoặc API Key, **không phải mật khẩu đăng nhập tài khoản chính**)

<Frame>
  <img src="https://mintcdn.com/chatbotx/ki-zrl-4XwRESz1z/images/chatbotx-email-smtp-providers-overview-1.png?fit=max&auto=format&n=ki-zrl-4XwRESz1z&q=85&s=43d1054820328c8ec1c45bd899671078" alt="Tổng quan các nhà cung cấp dịch vụ Email SMTP phổ biến" width="1024" height="576" data-path="images/chatbotx-email-smtp-providers-overview-1.png" />
</Frame>

Vui lòng mở rộng (click) vào nhà cung cấp Email tương ứng của bạn dưới đây để xem cách lấy Mật khẩu ứng dụng (App Password) hoặc SMTP Key.

<AccordionGroup>
  <Accordion title="1. Gmail / Google Workspace" icon="google">
    <Steps>
      <Step title="Bật Xác minh 2 bước">
        Đăng nhập vào tài khoản Google, truy cập phần **Bảo mật (Security)** và đảm bảo bạn đã bật **Xác minh 2 bước (2-Step Verification)**.
      </Step>

      <Step title="Tạo Mật khẩu ứng dụng">
        Vẫn trong phần **Bảo mật**, tìm mục **Mật khẩu ứng dụng (App Passwords)**.
      </Step>

      <Step title="Lấy mật khẩu">
        Nhập tên ứng dụng (ví dụ: `ChatbotX SMTP`) và nhấn **Tạo (Create)**. Google sẽ cung cấp cho bạn một chuỗi 16 chữ cái. Đây chính là **SMTP Password** của bạn.
      </Step>

      <Step title="Thông số kết nối">
        * **Host:** `smtp.gmail.com`
        * **Port:** `465` (SSL) hoặc `587` (TLS)
        * **Username:** Địa chỉ Gmail của bạn.

        <Note>
          Tham khảo thêm tài liệu chính thức: [Đăng nhập bằng Mật khẩu ứng dụng - Google Account Help](https://support.google.com/accounts/answer/185833)
        </Note>
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="2. Outlook / Office 365" icon="microsoft">
    <Steps>
      <Step title="Truy cập cài đặt bảo mật">
        Đăng nhập vào tài khoản Microsoft của bạn, đi tới **Security > Advanced Security Options**.
      </Step>

      <Step title="Tạo Mật khẩu ứng dụng">
        Đảm bảo **Two-step verification** đang được bật. Sau đó cuộn xuống mục **App passwords** và nhấp vào **Create a new app password**.
      </Step>

      <Step title="Lấy mật khẩu">
        Lưu lại mật khẩu vừa được tạo. Đây là **SMTP Password** của bạn.
      </Step>

      <Step title="Thông số kết nối">
        * **Host:** `smtp-mail.outlook.com` (hoặc `smtp.office365.com` cho tài khoản doanh nghiệp)
        * **Port:** `587` (TLS)
        * **Username:** Địa chỉ email Outlook/Office 365 của bạn.

        <Note>
          Tham khảo thêm tài liệu chính thức: [Quản lý Mật khẩu ứng dụng - Microsoft Support](https://support.microsoft.com/account-billing/how-to-get-and-use-app-passwords-5896ed9b-4263-e681-128a-a6f2979a7944)
        </Note>
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="3. SendGrid (Twilio)" icon="envelope-open-text">
    <Steps>
      <Step title="Tạo API Key">
        Đăng nhập SendGrid, vào **Settings > API Keys** và nhấp **Create API Key**.
      </Step>

      <Step title="Phân quyền">
        Chọn **Restricted Access**, cấp quyền **Mail Send > Full Access** và tiến hành tạo.
      </Step>

      <Step title="Lấy thông tin">
        Copy chuỗi API Key bắt đầu bằng `SG.`. Đây sẽ là **SMTP Password** của bạn.
      </Step>

      <Step title="Thông số kết nối">
        * **Host:** `smtp.sendgrid.net`
        * **Port:** `465` (SSL) hoặc `587` (TLS)
        * **Username:** `apikey` (Viết chính xác chữ "apikey", không phải email của bạn).

        <Note>
          Tham khảo thêm tài liệu chính thức: [Gửi Email với SMTP - Twilio SendGrid Docs](https://docs.sendgrid.com/for-developers/sending-email/getting-started-smtp)
        </Note>
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="4. Amazon SES" icon="aws">
    <Steps>
      <Step title="Truy cập SMTP Settings">
        Trong console AWS, mở dịch vụ **Amazon SES**, điều hướng tới **SMTP Settings**.
      </Step>

      <Step title="Tạo thông tin SMTP">
        Nhấp **Create My SMTP Credentials**. Hệ thống sẽ tạo một người dùng IAM mới có quyền gửi email.
      </Step>

      <Step title="Lấy Username và Password">
        Tải xuống hoặc copy ngay **SMTP Username** và **SMTP Password** được cung cấp ở màn hình cuối.
      </Step>

      <Step title="Thông số kết nối">
        * **Host:** (Tùy thuộc vào Region của bạn, ví dụ: `email-smtp.us-east-1.amazonaws.com`)
        * **Port:** `465` hoặc `587`
        * **Username:** Chuỗi SMTP Username vừa tạo.
        * **Password:** Chuỗi SMTP Password vừa tạo.

        <Note>
          Tham khảo thêm tài liệu chính thức: [Lấy thông tin đăng nhập SMTP - Amazon SES Developer Guide](https://docs.aws.amazon.com/ses/latest/dg/send-email-smtp.html)
        </Note>
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="5. Brevo (Sendinblue)" icon="paper-plane">
    <Steps>
      <Step title="Truy cập SMTP & API">
        Đăng nhập Brevo, nhấn vào tên tài khoản của bạn ở góc trên bên phải > **SMTP & API**.
      </Step>

      <Step title="Tạo SMTP Key mới">
        Chuyển sang tab **SMTP**, nhấp vào **Generate a new SMTP key**.
      </Step>

      <Step title="Lấy mật khẩu">
        Đặt tên cho key và copy chuỗi khóa vừa tạo.
      </Step>

      <Step title="Thông số kết nối">
        * **Host:** `smtp-relay.brevo.com`
        * **Port:** `587`
        * **Username:** Email đăng nhập Brevo của bạn.
        * **Password:** Chuỗi SMTP key vừa tạo.

        <Note>
          Tham khảo thêm tài liệu chính thức: [Thiết lập Brevo SMTP - Brevo Help Center](https://help.brevo.com/hc/en-us/articles/209432609-Set-up-Brevo-SMTP)
        </Note>
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>

## Bước 2: Tạo kênh Email

<Steps>
  <Step title="Thêm kênh Email mới">
    Trong ChatbotX, đi tới **Settings → Channels →** nhấp vào **Add SMTP**.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/AsF-QQXD77Aec07N/images/image-310.png?fit=max&auto=format&n=AsF-QQXD77Aec07N&q=85&s=dc222c9423ec324f9dba2e1be2365159" alt="Thêm kênh email mới" width="2992" height="1359" data-path="images/image-310.png" />
    </Frame>
  </Step>

  <Step title="Chọn nhà cung cấp (Provider)">
    Tìm và chọn nhà cung cấp dịch vụ Email của bạn từ danh sách thả xuống (ví dụ: Google (Gmail), Outlook, SendGrid, Amazon SES,...).

    <Frame>
      <img src="https://mintcdn.com/chatbotx/AsF-QQXD77Aec07N/images/image-311.png?fit=max&auto=format&n=AsF-QQXD77Aec07N&q=85&s=ef6ae15fb678bd1a72d417f1d715270f" alt="Chọn nhà cung cấp SMTP" width="1012" height="1147" data-path="images/image-311.png" />
    </Frame>
  </Step>

  <Step title="Nhập thông tin kết nối SMTP">
    Điền các thông tin xác thực SMTP đã lấy ở Bước 1. Các trường thông tin bao gồm:

    <Frame>
      <img src="https://mintcdn.com/chatbotx/AsF-QQXD77Aec07N/images/image-312.png?fit=max&auto=format&n=AsF-QQXD77Aec07N&q=85&s=cc3846bcf8e0b9bcbf4c3f5b9263c761" alt="Nhập thông tin kết nối SMTP" width="1008" height="1144" data-path="images/image-312.png" />
    </Frame>

    | Trường           | Mô tả                                                                                                 |
    | :--------------- | :---------------------------------------------------------------------------------------------------- |
    | **Host**         | Máy chủ SMTP của nhà cung cấp (ví dụ: `smtp.gmail.com`)                                               |
    | **Port**         | Cổng kết nối SMTP (thường là `587` hoặc `465`)                                                        |
    | **Username**     | Tên đăng nhập SMTP (thường là địa chỉ email)                                                          |
    | **Password**     | Mật khẩu ứng dụng hoặc SMTP Key (không phải mật khẩu đăng nhập chính)                                 |
    | **From Address** | Địa chỉ email sẽ hiển thị là người gửi khi khách hàng nhận được thư (ví dụ: `noreply@yourdomain.com`) |
  </Step>

  <Step title="Kết nối">
    Nhấp vào **Connect** để hoàn tất việc thiết lập cấu hình SMTP.
  </Step>
</Steps>

## Bước 3: Xin quyền (Opt-In) và Thu thập Email khách hàng

Trước khi có thể gửi Email cho khách hàng qua Flow của ChatbotX, bạn **bắt buộc** phải có hai yếu tố: Lưu trữ địa chỉ Email của họ và Khách hàng đã đồng ý nhận email (Email Opt-In).

<Steps>
  <Step title="Thu thập Email bằng User Input">
    Sử dụng khối (Block) \*\*Get User Data \*\*trong kịch bản để hỏi địa chỉ email của khách hàng. Trong phần Reply Format, chọn định dạng là **Email** và lưu kết quả vào **Output Custom Field** (ví dụ: trường `email`).

    <Frame>
      <img src="https://mintcdn.com/chatbotx/AsF-QQXD77Aec07N/images/image-317.png?fit=max&auto=format&n=AsF-QQXD77Aec07N&q=85&s=6f40b0d6b110cb2f83e9a083f2155fce" alt="Block Get User Data" width="3143" height="1815" data-path="images/image-317.png" />
    </Frame>
  </Step>

  <Step title="Đánh dấu Email Opt-in">
    Sau khi khách hàng cung cấp email, bạn cần tạo một khối hành động (Action block).

    * Nhấp vào dấu **+** và chọn **Perform Action**.
    * Nhấp vào khối Action vừa tạo, chọn mục **Email Actions**.
    * Lựa chọn **Opt In Email**. Trạng thái này là bắt buộc để hệ thống cho phép kích hoạt gửi thư sau này.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/AsF-QQXD77Aec07N/images/image-318.png?fit=max&auto=format&n=AsF-QQXD77Aec07N&q=85&s=24b8e7849c4d4f96e1d157d16aacba62" alt="Email Opt-in" width="3142" height="1814" data-path="images/image-318.png" />
    </Frame>
  </Step>
</Steps>

## Bước 4: Thiết lập gửi Email tự động trong Flow

Khi khách hàng đã đồng ý nhận email, bạn có thể tự động gửi thư ở bất kỳ đâu trong Flow.

<Steps>
  <Step title="Thêm Block Send Email">
    * Trong không gian làm việc của Flow, nhấp vào nút **+** (Add Block).
    * Lựa chọn khối **Send Email** trực tiếp từ menu.

    <Frame>
      <img src="https://mintcdn.com/chatbotx/AsF-QQXD77Aec07N/images/image-319.png?fit=max&auto=format&n=AsF-QQXD77Aec07N&q=85&s=70e6f215f2dd999f5676814a6b23f375" alt="block send email" width="3136" height="1808" data-path="images/image-319.png" />
    </Frame>
  </Step>

  <Step title="Soạn thảo nội dung Email">
    Trong cửa sổ cấu hình Send Email:

    * **To:** Mặc định hệ thống sẽ gửi tới email của người dùng hiện tại (nếu đã cung cấp). Bạn cũng có thể thiết lập để gửi email thông báo nội bộ cho nhóm của mình.
    * **Subject:** Tiêu đề của thư. Bạn có thể sử dụng biến (ví dụ: `{{first_name}}`) để cá nhân hóa tiêu đề.
    * **Body:** Nhập nội dung email. Trình soạn thảo hỗ trợ định dạng cơ bản, chèn ảnh, liên kết và sử dụng biến dữ liệu (Custom Fields).
  </Step>

  <Step title="Kiểm tra và Xuất bản">
    Nhấn nút Publish Flow của bạn. Hãy thử nghiệm tương tác với bot để kiểm tra xem hệ thống đã gửi thư tới hộp thư của bạn thành công hay chưa.
  </Step>
</Steps>

## Xử lý sự cố

Nếu hệ thống không thể gửi email thành công, hãy kiểm tra một số trường hợp phổ biến sau:

<AccordionGroup>
  <Accordion title="Lỗi: 'Authentication Failed' hoặc 'Invalid Login'" icon="circle-exclamation">
    * **Nguyên nhân:** Username hoặc Password của SMTP không chính xác.
    * **Khắc phục:** Không sử dụng mật khẩu đăng nhập chính. Đảm bảo bạn đã tạo và sử dụng **App Password** (Mật khẩu ứng dụng) hoặc **API Key/SMTP Key** riêng biệt như hướng dẫn ở Phần 1.
  </Accordion>

  <Accordion title="Lỗi kết nối Timeout hoặc Connection Refused" icon="network-wired">
    * **Nguyên nhân:** Sai SMTP Port hoặc bị tường lửa chặn.
    * **Khắc phục:** Hãy chắc chắn Port đi kèm đúng chuẩn mã hóa. Ví dụ: Port `465` phải chọn SSL, Port `587` phải chọn TLS. Nếu dùng Google Workspace, đảm bảo quyền truy cập IMAP/SMTP không bị tắt bởi quản trị viên.
  </Accordion>

  <Accordion title="Flow chạy qua khối Send Email nhưng thư không tới" icon="ban">
    * **Nguyên nhân:** Khách hàng chưa được cấp quyền (Email Opt-in) trong hệ thống.
    * **Khắc phục:** Kiểm tra dữ liệu Audience xem người dùng đó đã có Email và trạng thái **Opted-in** hay chưa. Đảm bảo Flow của bạn có bước chạy qua Action `Set Email Opt-In` trước khi tới `Send Email`.
  </Accordion>

  <Accordion title="Thư gửi bị rơi vào mục Thư rác (Spam)" icon="trash">
    * **Khắc phục:** Như khuyến cáo ở phần đầu, hãy cấu hình các bản ghi DNS (`SPF`, `DKIM`) cho tên miền hiển thị trên email gửi (From Email). Tránh gửi email có nội dung chứa quá nhiều ảnh mà không có text, hoặc sử dụng các từ ngữ "spammy".
  </Accordion>
</AccordionGroup>