Gửi email

govex-cloud-mail gửi email giao dịch qua SMTP: cấu hình provider linh hoạt trong bảng setting, render nội dung bằng FreeMarker template và lưu vết các email đã gửi.

Khi nào sử dụng

• Service cần gửi email giao dịch: kích hoạt tài khoản, thông báo, xác thực...
• Muốn nội dung email tách khỏi code dưới dạng template HTML, có thể chỉnh sửa mà không cần build lại.
• Cần gửi email bất đồng bộ để không chặn luồng nghiệp vụ và lưu vết những email đã gửi.

Cài đặt

Thêm dependency vào pom.xml — không khai version vì đã được quản lý qua BOM:

<dependency>
    <groupId>vn.govex.cloud</groupId>
    <artifactId>govex-cloud-mail</artifactId>
</dependency>

Nếu ứng dụng chưa dùng parent/BOM của Govex Cloud, xem hướng dẫn tại Cài đặt.

Cấu hình

Cấu hình provider nằm trong bảng setting của govex-cloud-config:

Key setting	Nội dung	Ghi chú
govex.message.setting.email_provider	JSON cấu hình provider	Gồm provider (customize/gmail), smtpUrl, port, safetyType (none/ssl), username, secret

• Trường secret được mã hoá khi lưu; có thể ghi cấu hình qua MailSettingService thay vì thao tác trực tiếp DB.
• Template tuỳ chỉnh có thể được lưu trong bảng mail_template theo type; listener đọc bản ghi này từ Redis cache nên thay đổi có hiệu lực khi cache được refresh.

Sử dụng

Khai báo loại email bằng cách implement MailType — mỗi loại trỏ tới một template HTML trong classpath:

public enum AccountMailType implements MailType {

    ACCOUNT_CREATED("ACCOUNT_CREATED", "Tạo tài khoản",
            "mail/content/account-created.html",
            "Tài khoản của bạn đã được tạo",
            "no-reply@example.com");

    private final String code;
    private final String desc;
    private final String content;
    private final String subject;
    private final String sender;

    AccountMailType(String code, String desc, String content, String subject, String sender) {
        this.code = code;
        this.desc = desc;
        this.content = content;
        this.subject = subject;
        this.sender = sender;
    }

    @Override public String getCode() { return code; }
    @Override public String getDesc() { return desc; }
    @Override public String getContent() { return content; }
    @Override public String getSubject() { return subject; }
    @Override public String getName() { return desc; }
    @Override public String getSender() { return sender; }
}

Template là file FreeMarker, ví dụ src/main/resources/mail/content/account-created.html:

<p>Xin chào ${username},</p>
<p>Tài khoản của bạn đã được tạo lúc ${time}.</p>

Gửi email qua MailMsgEventPublish:

@Service
@RequiredArgsConstructor
public class AccountService {

    private final MailMsgEventPublish mailMsgEventPublish;

    public void notifyAccountCreated(String email, String username) {
        Map<String, Object> variables = new HashMap<>();
        variables.put("username", username);
        mailMsgEventPublish.publish(AccountMailType.ACCOUNT_CREATED, email, variables);
    }
}

Dependency tự bổ sung các biến dùng chung vào tham số template trước khi render: time (thời điểm hiện tại), client_name, client_description, user_email (người nhận). Chỉ cần truyền thêm biến nghiệp vụ riêng.

Cấu hình provider qua service:

mailSettingService.saveMailProviderConfig(new MailProviderSaveParam()
        .setProvider(MailProvider.GMAIL)
        .setUsername("no-reply@example.com")
        .setSecret("app-password"));

• Với GMAIL, dependency tự điền smtpUrl/port/safetyType theo provider; với CUSTOMIZE cần truyền đủ các trường này.
• MailSettingService còn có disableMailProvider() để tắt gửi mail và getMailProviderConfig() để đọc cấu hình hiện tại; thay đổi được áp dụng ngay sau khi refresh, không cần khởi động lại.

Lưu ý

• Cần có govex-cloud-config (bảng setting), govex-cloud-redisson (cache), govex-cloud-data-jpa; bảng emails và mail_template phải tồn tại trước khi dùng.
• Chưa cấu hình provider → MailMsgEventPublish.publish ném MAIL_SERVICE_NOT_CONFIGURED; người nhận trống thì bỏ qua và ghi log cảnh báo.
• Việc gửi chạy bất đồng bộ (@Async) nên phụ thuộc cấu hình async và ThreadPoolTaskExecutor của ứng dụng host; cần có bean RedisTemplate để đọc template tuỳ chỉnh từ cache.
• Cần một hoặc nhiều MailType do ứng dụng khai báo để làm đầu mối gửi mail; lỗi render template hoặc SMTP được ghi log và bọc thành exception gửi mail.