email caixa

Home > E-mail > Ler a caixa postal

Ler a caixa postal (IMAP e POP3)

Important

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

Nível: iniciante

Em uma frase: TRALIMAPClient lê e organiza uma caixa postal no servidor (pastas, busca, marcações, mover, apagar, aviso de mensagem nova); TRALPOP3Client baixa as mensagens e apaga do servidor.

Você vai precisar: o pacote RALModuleMailPackage (e-mail); OpenSSL ao lado do executável para TLS; o endereço do servidor IMAP ou POP3 e o login.

IMAP ou POP3?

você quer	use
ler sem tirar do servidor, em vários aparelhos	IMAP
pastas, busca no servidor, marcar como lida	IMAP
saber na hora que chegou mensagem	IMAP (WaitForChanges)
baixar tudo e apagar do servidor (uma caixa de entrada de pedidos, por exemplo)	POP3

IMAP

uses RALMailMIME, RALSMTPClient, RALIMAPClient;

var
  vIMAP: TRALIMAPClient;
  vUIDs: TStringList;
  vMsg: TRALMailMessage;
  vInt: Integer;
begin
  vIMAP := TRALIMAPClient.Create(nil);
  vUIDs := TStringList.Create;
  try
    vIMAP.Host := 'imap.minhaempresa.com.br';
    vIMAP.Security := msImplicitTLS;            // porta 993
    vIMAP.UserName := 'pedidos@minhaempresa.com.br';
    vIMAP.Password := 'senha';
    vIMAP.Select('INBOX');
    vIMAP.Search('UNSEEN', vUIDs);              // as não lidas
    for vInt := 0 to vUIDs.Count - 1 do
    begin
      vMsg := TRALMailMessage.Create;
      try
        vIMAP.FetchMessage(StrToInt(vUIDs[vInt]), vMsg);
        Processar(vMsg);
        vIMAP.SetFlags([StrToInt(vUIDs[vInt])], '\Seen');
        vIMAP.Move([StrToInt(vUIDs[vInt])], 'Processados');
      finally
        vMsg.Free;
      end;
    end;
    vIMAP.Disconnect;
  finally
    vUIDs.Free;
    vIMAP.Free;
  end;
end;

• Toda mensagem é chamada pelo UID, que não muda entre sessões enquanto o UIDValidity da pasta for o mesmo.
• Search aceita os critérios do IMAP: ALL, UNSEEN, FLAGGED, FROM "ana", SUBJECT "pedido", SINCE 1-Nov-2026, combinados com espaço.
• FetchSummaries traz a lista (remetente, assunto, data, tamanho, marcações) sem baixar as mensagens; FetchMessage baixa uma inteira, sem marcar como lida (APeek); FetchRaw grava o original num stream.
• Move usa o comando MOVE quando o servidor tem; senão copia e apaga. Delete apaga só as mensagens pedidas (com UIDPLUS).
• Append grava uma mensagem numa pasta (a pasta "Enviados" depois de enviar por SMTP, por exemplo).
• Pastas: ListMailboxes, CreateMailbox, RenameMailbox, DeleteMailbox. O separador de níveis muda de servidor para servidor (/ no Gmail, . no Dovecot): use Delimiter para montar o nome. Nomes acentuados funcionam (UTF-7 modificado ou UTF-8, conforme o servidor).

Aviso de mensagem nova

  vIMAP.Select('INBOX');
  while not Terminated do
    if vIMAP.WaitForChanges(5 * 60 * 1000) then   // até 5 minutos
      BuscarNovas;

WaitForChanges usa o IDLE: o servidor avisa assim que a pasta muda, sem o programa perguntar de tempo em tempo. Rode num thread: a chamada espera.

POP3

uses RALMailMIME, RALSMTPClient, RALPOP3Client;

  vPOP.Host := 'pop.minhaempresa.com.br';
  vPOP.Security := msImplicitTLS;               // porta 995
  vPOP.UserName := 'pedidos@minhaempresa.com.br';
  vPOP.Password := 'senha';
  vPOP.Stat(vQtd, vTamanho);
  for vInt := 1 to vQtd do
  begin
    vPOP.Retrieve(vInt, vMsg);
    Processar(vMsg);
    vPOP.Delete(vInt);
  end;
  vPOP.Disconnect;                              // só aqui o servidor apaga

• As mensagens são numeradas de 1 a N na sessão; UIDL dá identificadores que duram entre sessões (para não baixar de novo o que já baixou).
• O que foi marcado com Delete só some no Disconnect (QUIT); Reset desmarca; se a conexão cair antes, nada é apagado.
• Top(n, 0, stream) traz só o cabeçalho.

Login e segurança

Os dois clientes usam as mesmas propriedades do envio: Security (msStartTLS, msImplicitTLS...), SSL (as regras de certificado do cliente REST), UserName/Password ou AccessToken (XOAUTH2/OAUTHBEARER, Gmail e Microsoft 365) e AuthMethod (maAuto escolhe o mais forte que o servidor oferece; SCRAM-SHA-256 quando há). OnLog mostra a conversa com a senha mascarada.

Erros comuns

sintoma	causa	o que fazer
ERALIMAPError "NO ... authentication failed"	senha errada; no Gmail, senha normal com 2 fatores	senha de app ou OAuth2
Invalid mailbox name ao criar pasta	separador errado para o servidor	monte o nome com Delimiter
POP3 não apaga	o programa terminou sem Disconnect	chame Disconnect no fim
a mesma mensagem é baixada de novo pelo POP3	número da sessão usado como identificador	guarde o UIDL

Veja também

• E-mail, enviar, receber como servidor