Email

Gửi email giao dịch từ ứng dụng của bạn. Quản lý danh tính người gửi và theo dõi quá trình gửi tại Admin > Email trong ứng dụng.

Mọi ứng dụng Proyecta đều có thể gửi email giao dịch. Xác minh danh tính người gửi, rồi gửi email từ code của ứng dụng — không cần tạo tài khoản riêng với bất kỳ nhà cung cấp email nào.

Phần Email

Mở Admin > Email trong builder — hoặc truy cập /admin trên trang đã publish. Phần này gồm hai mục:

Mục	Chức năng
Identities	Thêm và xác minh địa chỉ email hoặc tên miền người gửi
Sent	Xem lịch sử email đã gửi cùng trạng thái gửi (sent, delivered, bounced, v.v.)

Bạn có thể thêm danh tính người gửi mới và xem lịch sử gửi email — tất cả mà không cần viết code.

Quy trình thiết lập hai bước

1. Tạo và xác minh danh tính người gửi (một địa chỉ email hoặc tên miền) trong bảng quản trị
2. Gửi email — từ ứng dụng bằng useSendEmail(), hoặc trực tiếp từ bảng quản trị cho các chiến dịch

Gửi từ địa chỉ dùng chung (@proyectamail.com)

Cách đơn giản nhất là đăng ký một địa chỉ trên tên miền gửi chung của Proyecta, @proyectamail.com. Địa chỉ này được xác minh ngay lập tức khi bạn tạo — vì nền tảng đã sở hữu tên miền đó, bạn không cần thiết lập bất kỳ bản ghi DNS nào.

Bạn thực hiện điều này trong phần Emails của bảng quản trị ứng dụng: nhập địa chỉ mong muốn và nó sẵn sàng sử dụng ngay.

Địa chỉ đơn lẻ chỉ hoạt động với @proyectamail.com. Nếu bạn yêu cầu một địa chỉ trên tên miền khác (ví dụ: hello@myapp.com), yêu cầu sẽ bị từ chối — để gửi từ tên miền của riêng bạn, hãy xác minh toàn bộ tên miền đó (xem bên dưới). Mỗi địa chỉ dùng chung được đặt trước trên toàn hệ thống, vì vậy không có hai ứng dụng nào có thể gửi với cùng một địa chỉ @proyectamail.com.

Xác minh tên miền riêng (Pro)

Để gửi từ tên miền của bạn — từ bất kỳ địa chỉ nào trên đó (hello@, support@, noreply@, v.v.) — hãy xác minh toàn bộ tên miền. Khác với địa chỉ @proyectamail.com dùng chung, tên miền tùy chỉnh không được xác minh ngay lập tức.

Thêm tên miền trong cùng phần Emails. Hệ thống sẽ đăng ký với nhà cung cấp email và hiển thị các bản ghi SPF, DKIM và DMARC để bạn publish lên DNS. Người gửi sẽ ở trạng thái pending cho đến khi các bản ghi đó được lan truyền và nhà cung cấp xác nhận, sau đó chuyển sang verified — hãy dùng nút kiểm tra lại sau khi bạn đã publish các bản ghi.

Xác minh tên miền qua DNS được triển khai đầy đủ — các bản ghi được tạo bởi nhà cung cấp và mỗi lần kiểm tra lại sẽ cập nhật trạng thái từ họ.

Bên trong hệ thống: Proyecta xác thực tên miền gửi của bạn với nhà cung cấp danh tính email (Resend) và gửi tin nhắn qua nhà cung cấp giao dịch (SendGrid). Bạn không cần quản lý tài khoản với bất kỳ dịch vụ nào trong số đó.

Gửi email từ ứng dụng

Từ các trang trong ứng dụng, bạn gửi email bằng hook useSendEmail(). Bạn chọn một template và truyền variables; nền tảng render nội dung theo ngôn ngữ của ứng dụng và gửi đi:

import { useSendEmail } from '@/hooks/useEmail.ts';

function ConfirmButton({ booking }) {
    const { send, isPending, error } = useSendEmail();

    return (
        <button
            disabled={isPending}
            onClick={() =>
                send({
                    template: 'booking_confirmation',
                    variables: { date: booking.date, service: booking.service },
                })
            }
        >
            Email me the details
        </button>
    );
}

Lưu ý những gì bạn không cần truyền: người nhận, tiêu đề, hay HTML. Mỗi template tự khai báo đối tượng nhận:

• self (xác nhận đặt chỗ/đơn hàng, chào mừng) → địa chỉ của chính người dùng đang đăng nhập, lấy từ session của họ.
• owner (owner_alert) → các admin của ứng dụng.

Cả hai đều yêu cầu session đăng nhập. Đây là thiết kế có chủ đích, không phải thiếu sót: publishable key dùng để xác thực lời gọi được nhúng trong source code trang, nên nếu cho phép gửi đến bất kỳ người nhận nào, bất kỳ ai cũng có thể dùng ứng dụng của bạn làm relay spam. Để thông báo cho bản thân từ khách vô danh, hãy dùng form — các lần gửi form đã tự động gửi email cho chủ sở hữu và xác nhận cho người gửi, và luồng đó không thể bị làm giả từ trình duyệt.

Lỗi trả về dưới dạng PlatformApiError: 401 (cần session), 403 (template chưa được bật cho ứng dụng này), 429 (bị giới hạn tốc độ — hiển thị thông báo và cho phép thử lại), 422 (không có địa chỉ email trong hồ sơ).

Theo dõi quá trình gửi

Tab Sent trong bảng quản trị liệt kê tất cả email ứng dụng đã gửi cùng sự kiện gửi gần nhất — delivered, opened, clicked, bounced, complained — vì vậy thông thường bạn không cần viết code cho việc này.

Mỗi mục hiển thị trạng thái — sent, delivered, opened, clicked, bounced, hoặc complained — và bạn có thể mở bất kỳ tin nhắn nào để xem nội dung HTML và text chính xác đã được gửi đi. Nếu việc gửi đang thất bại, đây là nơi đầu tiên cần kiểm tra.

Để AI thực hiện thay bạn

Bạn không cần tự viết tay những điều này:

• "Verify hello@myapp.com as a sending identity."
• "Email the customer a confirmation after they finish booking."
• "After a successful checkout, send the customer their receipt."
• "Show me the last 20 emails we've sent and whether they bounced."

Lưu ý

• Địa chỉ from phải là danh tính đã được xác minh. Gửi bằng địa chỉ chưa xác minh sẽ trả về lỗi.
• Giới hạn hàng tháng áp dụng dựa trên gói Proyecta của bạn.

Sắp ra mắt

• Template editor — thiết kế template email giao dịch trực quan ngay trong builder
• Bulk/batch send endpoint cho các chiến dịch gửi email hàng loạt