Skip to content
mobius1qwe edited this page Nov 17, 2026 · 1 revision

Home > E-mail > Enviar por REST e por ação

Enviar e-mail por REST e por ação

Important

Em desenvolvimento (2.0). Ainda não está numa versão lançada e pode mudar.

Nível: intermediário

Em uma frase: TRALMailRestModule põe uma rota POST /mail/send no seu servidor RAL para que qualquer cliente HTTP mande e-mail, e TRALSendMail é uma ação que envia uma mensagem montada na IDE, de um botão ou de um handler de rota.

Você vai precisar: o pacote RALModuleMailPackage (e-mail); um TRALSMTPClient configurado (enviar) e, para mandar em segundo plano, um TRALMailQueue.

A rota REST

Coloque um TRALMailRestModule (paleta RAL - Modules) no módulo de dados ou no formulário do servidor e ligue Client (envio na hora) ou Queue (envio em segundo plano). A rota é POST <Domain>/send, com Domain padrão /mail.

propriedade para
Client o TRALSMTPClient cujas configurações enviam (uma cópia por pedido simultâneo)
Queue o TRALMailQueue para onde a mensagem vai em vez de sair na hora
DefaultFrom o remetente quando o pedido não diz nenhum (Nome <a@x>)
AllowedFrom outros remetentes permitidos: um endereço, @dominio ou *
MaxRecipients máximo de destinatários (To, Cc e Bcc juntos) por pedido; padrão 50, 0 = sem limite
OnBeforeSend muda a mensagem ou recusa o pedido

O corpo em JSON

campo conteúdo
from texto "Nome <a@x>" ou objeto {name, address}; vazio usa DefaultFrom
to, cc, bcc, replyTo uma lista em texto ("a@x, B <b@y>") ou um array de textos ou objetos
subject, text, html assunto e corpo
priority high, normal ou low
headers objeto com cabeçalhos extras; só X-* e List-*
attachments array de {fileName, contentType, content, inline, contentId}; content em base64
curl -X POST http://localhost:8000/mail/send \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"from":"Vendas <vendas@minhaempresa.com.br>",
       "to":["cliente@exemplo.com"],
       "subject":"Seu pedido nº 1234",
       "text":"Olá, José. Segue a nota fiscal.",
       "html":"<p>Olá, <b>José</b>.</p><img src=\"cid:logo\">",
       "attachments":[{"fileName":"logo.png","contentType":"image/png",
                       "content":"iVBORw0KGgo...","inline":true,"contentId":"logo"}]}'

O corpo em formulário

Com multipart/form-data ou application/x-www-form-urlencoded valem os mesmos campos de texto. No multipart, cada arquivo vira um anexo; um campo de arquivo chamado cid:<id> vira uma parte embutida, usada no HTML como cid:<id>.

curl -X POST http://localhost:8000/mail/send -H "Authorization: Bearer $TOKEN" \
  -F from="vendas@minhaempresa.com.br" -F to="cliente@exemplo.com" \
  -F subject="Nota fiscal" -F html='<p>Veja <img src="cid:logo"></p>' \
  -F "nota=@1234.pdf" -F "cid:logo=@logo.png"

As respostas

status quando
200 enviado: messageId e recipients[{address, accepted, code, reply}], um por destinatário
202 com Queue: jobId e messageId; a entrega acontece depois
400 corpo malformado, nenhum destinatário, destinatários demais (MaxRecipients) ou CR/LF/NUL num campo que vira cabeçalho
403 remetente fora de DefaultFrom e AllowedFrom
502 o servidor SMTP recusou; a resposta traz smtpCode e enhancedCode
503 o módulo não tem Client nem Queue

Um erro vem como {"error": "texto"}. Sem Queue, um destinatário recusado não vira 502: ele aparece com accepted falso em recipients.

OnBeforeSend

uses RALRequest, RALMailMIME;

procedure TForm1.MailRestBeforeSend(Sender: TObject; ARequest: TRALRequest;
  AMessage: TRALMailMessage; var AStatus: IntegerRAL; var AError: StringRAL);
begin
  AMessage.Subject := '[Site] ' + AMessage.Subject;   // muda a mensagem
  if AMessage.Attachments.Count > 5 then
  begin
    AStatus := 413;                                    // >= 400 recusa o pedido
    AError := 'anexos demais';
  end;
end;

No Lazarus sem {$MODE DELPHI}, atribua com @: RALMailRestModule1.OnBeforeSend := @MailRestBeforeSend;.

Segurança

Warning

Sem autenticação a rota é um relay aberto: qualquer um que alcance o servidor manda e-mail em nome do seu domínio. Proteja com um plugin de autenticação como qualquer outra rota.

  • Só DefaultFrom e as entradas de AllowedFrom podem ser remetentes (403 nos outros). * libera qualquer um: use só em rede fechada.
  • Um CR, LF ou NUL em qualquer campo que vira cabeçalho é 400 (injeção de cabeçalho), e headers aceita só X-* e List-*.
  • Cada pedido simultâneo usa a sua própria cópia de Client (e a sua conexão SMTP): o módulo copia as configurações, então um só Client basta.

A ação TRALSendMail

Na paleta de ações da IDE (categoria RAL, em listas de ações VCL, FMX e LCL), TRALSendMail envia uma mensagem sem código.

propriedade ou evento para
Client ou Queue quem envia; com os dois, a Queue vence
Message o TRALMailMessage preenchido no Object Inspector; uma cópia sai a cada envio
OnPrepare(Sender, AMessage) muda a cópia antes de sair (um destinatário digitado, um corpo montado)
OnSent(Sender, AMessageID, AJobID) depois do envio; AJobID só vem quando foi para a fila
OnFailed(Sender, AError) falha: com ele atribuído não há exceção e Send devolve False

A ação fica habilitada só com Client ou Queue. Ligue-a a um botão e ela envia ao clicar; com OnExecute próprio, é o seu handler que roda.

uses RALMailMIME;

procedure TForm1.SendMail1Prepare(Sender: TObject; AMessage: TRALMailMessage);
begin
  AMessage.Recipients.Add(edtEmail.Text);
  AMessage.Text := 'Olá, ' + edtNome.Text;
end;

procedure TForm1.SendMail1Sent(Sender: TObject; const AMessageID, AJobID: StringRAL);
begin
  ShowMessage('Enviado: ' + AMessageID);
end;

procedure TForm1.SendMail1Failed(Sender: TObject; AError: Exception);
begin
  ShowMessage('Falhou: ' + AError.Message);
end;

De um handler de rota

Send também pode ser chamado do código, inclusive de uma rota do servidor:

procedure TForm1.EnviarBoasVindas(ARequest: TRALRequest; AResponse: TRALResponse);
begin
  if SendMail1.Send then
    AResponse.Answer(HTTP_OK, '{"ok":true}', rctAPPLICATIONJSON)
  else
    AResponse.Answer(HTTP_BadGateway, '{"ok":false}', rctAPPLICATIONJSON);
end;

A ação mantém uma cópia de Client por thread, então vários pedidos podem chamar Send ao mesmo tempo. Se OnPrepare muda a mensagem, ela muda a cópia, nunca a Message da ação.

No Lazarus sem {$MODE DELPHI}, use @ nos eventos: SendMail1.OnPrepare := @SendMail1Prepare;.

Erros comuns

sintoma causa o que fazer
503 o módulo não tem Client nem Queue ligue um dos dois
403 o from não está em DefaultFrom nem em AllowedFrom acrescente o endereço ou @dominio
400 "too many" mais destinatários que MaxRecipients aumente o limite ou divida o envio
400 sem motivo aparente quebra de linha num campo (assunto, nome) tire CR/LF do texto
502 o servidor SMTP recusou (smtpCode, enhancedCode) veja a resposta no envio
a ação fica desabilitada sem Client nem Queue ligue um deles
Send levanta exceção OnFailed não está atribuído atribua OnFailed ou trate com try..except

Veja também

  • Enviar e-mail: TRALSMTPClient, fila e DKIM
  • Mensagens: TRALMailMessage
  • Autenticação: proteger a rota
  • Rotas: como é um handler
  • Exemplo: PascalRAL-Samples, Delphi/Console/MailRestExample e Lazarus/Console/MailRestExample

Começar

Servidor

MQTT 🚧

E-mail 🚧

Chatbot 🚧

Cliente

Motores

Avançado

Ajuda

🚧 = em desenvolvimento, pode mudar

Clone this wiki locally