Repository navigation
email rest
Home > E-mail > Enviar 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.
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 |
| 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"}]}'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"| 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.
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;.
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ó
DefaultFrome as entradas deAllowedFrompodem 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
headersaceita sóX-*eList-*. - 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óClientbasta.
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;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;.
| 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
|
-
Enviar e-mail:
TRALSMTPClient, fila e DKIM -
Mensagens:
TRALMailMessage - Autenticação: proteger a rota
- Rotas: como é um handler
- Exemplo:
PascalRAL-Samples,Delphi/Console/MailRestExampleeLazarus/Console/MailRestExample
Começar
Servidor
- Rotas e parâmetros
- Rotas avançadas: tipos, grupos, versões 🚧
- Ler o pedido e responder
- Objetos no corpo 🚧
- Resposta em fluxo 🚧
- Plugins 🚧
- Serviços (contêiner de dependências) 🚧
- Barramento de eventos 🚧
- Tarefas em segundo plano 🚧
- Recursos com estado 🚧
- Autenticação
- Banco de dados (DBWare)
- Servir site e arquivos
- JSON-RPC 2.0 🚧
- GraphQL 🚧
- Servidor MCP (IA) 🚧
-
Protocol Buffers 🚧
- gRPC 🚧
- WebSocket 🚧
- Hubs (WebSocket) 🚧
- SignalR 🚧
- Swagger e Postman
- Servidor SOAP 🚧
- WS-Security 🚧
- HTTPS
- Criptografia ponto a ponto
- Segurança para produção
- Colocar no ar
- Desempenho
- Testes em memória 🚧
MQTT 🚧
- O que é e quando usar 🚧
- Cliente MQTT 🚧
- Broker MQTT 🚧
- MQTT-SN 🚧
- Ponte REST 🚧
- Segurança 🚧
- Rede ruim 🚧
E-mail 🚧
- Mensagens 🚧
- Enviar 🚧
- Enviar por REST e ação 🚧
- Receber 🚧
- Ler a caixa postal 🚧
- Verificar o que chega 🚧
- Servir caixas postais 🚧
- S/MIME 🚧
- OpenPGP 🚧
Chatbot 🚧
- O robô e os canais 🚧
- Telegram 🚧
- Gateways REST (WhatsApp não oficial) 🚧
- Discord 🚧
- Slack 🚧
- Microsoft Teams 🚧
- Conversa em etapas 🚧
Cliente
Motores
- Qual motor escolher?
- Compatibilidade
- Recursos
- QUIC
- Motor NgHttp2 (HTTP/2) 🚧
- Motor XSocket 🚧
- Motor AdvancedHTTP (experimental) 🚧
Avançado
Ajuda
- Problemas comuns
- Atualizar o Indy
- Várias versões do Delphi
- Vídeos e guias
- Módulos de terceiros
- Licenças
- Contribuir
- Roadmap e changelog
🚧 = em desenvolvimento, pode mudar