APIs e Microsserviços

2 jun, 2016

Enviando e-mails utilizando a API do Oracle APEX

Publicidade

Olá, pessoal! Tudo certo?

Hoje vou exemplificar como enviar e-mails utilizando a API APEX_MAIL do Oracle APEX. Essa API permite enviar facilmente e-mails no formato texto ou HTML, com ou sem anexos por meio de um bloco PL/SQL independente.

APEX_MAIL

Na package APEX_MAIL da API temos 3 procedures principais:

SEND

Procedure responsável por enviar as mensagens de e-mail. Quando essa procedure é executada, ela gera um registro na tabela APEX_MAIL_QUEUE para que seja enviada de fato para o servidor de e-mail.

APEX_MAIL.SEND(
    p_to                        IN    VARCHAR2,
    p_from                      IN    VARCHAR2,
    p_body                      IN  [ VARCHAR2 | CLOB ],
    p_body_html                 IN  [ VARCHAR2 | CLOB ] DEFAULT NULL,
    p_subj                      IN    VARCHAR2 DEFAULT NULL,
    p_cc                        IN    VARCHAR2 DEFAULT NULL,
    p_bcc                       IN    VARCHAR2 DEFAULT NULL,
    p_replyto                   IN    VARCHAR2);

Veja que podemos enviar mensagens em texto por meio do parâmetro P_BODY ou mensagens em HTML pelo parâmetro P_BODY_HTML.

Também podemos usar o parâmetro P_REPLYTO para determinar para qual endereço o recebedor do e-mail poderá responder.

ADD_ATTACHMENT

Procedure responsável por anexar arquivos ao e-mail. É possível anexar quantos arquivos forem necessários.

APEX_MAIL.ADD_ATTACHMENT(
    p_mail_id                   IN    NUMBER,
    p_attachment                IN    BLOB,
    p_filename                  IN    VARCHAR2,
    p_mime_type                 IN    VARCHAR2);

Você pode recuperar o anexo de qualquer tabela que tenha um campo do tipo BLOB. Como da tabela APEX_APPLICATION_FILES, que geralmente é utilizada para guardar temporariamente os arquivos carregados no APEX.

Na tabela APEX_MAIL_ATTACHMENTS, são gravados os anexos de cada e-mail enviado.

PUSH_QUEUE

Procedure responsável por efetivar o envio do e-mail. É necessário passar como parâmetro o endereço e a porta do servidor de e-mail responsável pelo envio, quando não forem informadas as configurações que serão herdadas da configuração default da Workspace.

APEX_MAIL.PUSH_QUEUE(
    p_smtp_hostname             IN    VARCHAR2 DEFAULT NULL,
    p_smtp_portno               IN    NUMBER   DEFAULT NULL);

Exemplo

DECLARE
    numID NUMBER;
BEGIN
    ---Envia o e-mail
   numID := APEX_MAIL.SEND( p_to        => 'all@all.com',
                            p_from      => 'leonardo.litz@gmail.com',
                            p_subj      => 'Exemplo E-mail com Anexo',
                            p_body      => 'Por favor! Olhe o conteúdo do Anexo',
                            p_body_html => '<b>Por favor!</b> Olhe o conteúdo do Anexo');
        
       
    
    FOR c1 IN (SELECT filename, blob_content, mime_type 
                 FROM APEX_APPLICATION_FILES
                WHERE ID IN (123,456)) LOOP
        --Anexa os arquivos da aplicação no e-mail através do ID gerado anteriormente    
    
    
        APEX_MAIL.ADD_ATTACHMENT(p_mail_id    => numID,
                                 p_attachment => c1.blob_content,
                                 p_filename   => c1.filename,
                                 p_mime_type  => c1.mime_type);
                                 
    END LOOP;
    COMMIT;
    
    ---Faz o envio do email para o sevidor de e-mail passado como parâmetro
    ---Quando não informado, herda das configurações da Workspace
    APEX_MAIL.PUSH_QUEUE(P_SMTP_HOSTNAME => '127.0.0.0',
                         P_SMTP_PORTNO   => '25');
    

END;

Entendimento

Vamos entender como funciona o fluxo do processo de envio de e-mails no Oracle APEX:

1 – É necessário que o processo seja executado por meio de alguma aplicação dentro do Oracle APEX.

2 – Coloque o código em um Process:

apex-1

3 – Quando executada a procedure SEND, a mensagem é gravada em uma tabela intermediária chamada APEX_MAIL_QUEUE, onde ficam todas as mensagens pendentes de serem enviadas ao servidor de e-mail.

4 – Para efetivar o envio do e-mail (enviar ao servidor de e-mail), é necessário executar a procedure PUSH_QUEUE. O registro ficará nessa tabela até que o e-mail consiga ser enviado. Uma solução muito comum é deixar um JOB agendado para efetuar a sua execução de tempos em tempos.

5 – Para cada tentativa de envio efetivo do e-mail, um registro é criado na tabela APEX_MAIL_LOG. Na coluna MAIL_SEND_ERROR, estão os erros ao tentar enviar o e-mail.

Essa arquitetura de uma tabela intermediária para envio de e-mails é utilizada para evitar que o processo principal pare, pois é comum que o servidor de e-mail não responda ou que esteja indisponível.

Conclusão

Para você aumentar as suas possibilidades, é muito importante conhecer as principais APIs do Oracle APEX. No caso exemplificado acima, é possível encapsular a rotina em uma package de sua aplicação e reutilizá-la diversas vezes.

Para acessar a aplicação demo da nossa série de artigos utilize este link.

  • Usuário: demo
  • Senha: imasters