Voltar

Mail (fw.Mail)

Serviço de e-mail de primeira classe, igual fw.DB/fw.Cache/fw.Queue — conectado automaticamente no boot a partir de MAIL_* no .env, disponível em qualquer app sem nenhuma configuração extra.

Ativar

MAIL_ENABLED=true
MAIL_HOST=smtp.exemplo.com.br
MAIL_PORT=465            # 465 = TLS implícito (SMTPS) automático; outra porta = STARTTLS
[email protected]
MAIL_PASSWORD=sua-senha

fw.Mail fica nil se MAIL_ENABLED=false, se MAIL_HOST/MAIL_USER estiverem vazios, ou se o servidor SMTP estiver inacessível no boot — ao contrário de Cache/Queue (que sempre caem para um fallback em memória), não existe "envio de e-mail" que funcione sem servidor de verdade. Sempre cheque fw.Mail != nil antes de usar.

Enviar

import "kyrux/core/mail"

err := fw.Mail.Send(ctx.Request.Context(), mail.Message{
    From:    "[email protected]",
    ReplyTo: "[email protected]", // opcional
    To:      []string{"[email protected]"},
    Cc:      []string{"[email protected]"},  // opcional
    Bcc:     []string{"[email protected]"}, // opcional
    Subject: "Assunto",
    Text:    "Corpo em texto puro",
    HTML:    "<p>Corpo em HTML</p>", // opcional — se vazio, envia só Text
    Attachments: []mail.Attachment{
        {Filename: "nota.pdf", Content: pdfBytes, ContentType: "application/pdf"},
    },
})

Assíncrono via Queue

Se QUEUE_ENABLED=true, fw.Mail.Send() enfileira a mensagem em fw.Queue e devolve o controle quase na hora — a entrega de verdade acontece depois, num worker (pool, retry com backoff automático em falha transitória, drenagem no shutdown). Sem isso, a requisição HTTP ficaria presa esperando a ida e volta de uma sessão SMTP, que pode levar segundos.

Sem QUEUE_ENABLED=true, Send é síncrono — o erro devolvido já é o de entrega de verdade. Com fila, o erro devolvido por Send é só de enfileirar (fila cheia, fila encerrada); falhas de entrega acontecem assíncronas e só aparecem nos logs e no retry automático da fila, nunca de volta pro caller.

Implementado em core/mail.Queued (core/mail/queued.go) — reaproveita core/queue sem nenhuma dependência nova; funciona também com QUEUE_DRIVER=redis (payload serializado em JSON entre réplicas).

Trocar de provedor

fw.Mail é montado sobre core/adapters/smtp no bootstrap. Para SendGrid/SES (sem sugar automático — SDK de terceiros), monte você mesmo com core.UseModule e mail.NewQueued(sender, fw.Queue) — ver Integrações.