A utilização dessa API não é recomendada em ambientes WEB, pois a mesma pode solicitar informações ao usuário e, no caso de executar o Blat, o usuário do IIS deverá ter permissão para efetuar a tarefa de envio e rodar o aplicativo Blat.
A include utapi019.i contém as definições das temp-table's tt-envio2, tt-mensagem e tt-erro que devem ser passadas como parâmetros à API.
A include utapi019.i1 contém a definição da temp-table tt-paramEmail e chamada para a include utapi019.i, resultando na definição de todas as temp-table's necessárias para chamadas à API.
É possível enviar e-mail e FAX em ambiente Windows e apenas e-mail em ambiente UNIX.
Será utilizado Outlook ou Blat no ambiente Windows ou comando sendmail no ambiente UNIX para envio de e-mail e será utilizado Outlook para envio de FAX.
O Blat é um software freeware para envio de e-mail via protocolo SMTP, encontra-se no diretório (interfac/mail).
Quando for utilizado envio de e-mail numa sessão background do Progress(batch-mode) e o ambiente for Windows, a API utilizará sempre o Blat.
No envio da mensagem através de ambiente UNIX, o sendmail e o uuencode devem estar configurados corretamente. Para testar o funcionamento do comando, digite no prompt, usando o mesmo usuário e na mesma pasta em que a API será executada, os respectivos comandos sendmail e uuencode. A execução destes programas não deve apresentar erros. Caso ocorram erros deve-se entrar em contato com a equipe de suporte do sistema operacional do servidor.
A API possui um evento de UPC chamado eMailBlat, que permite ao cliente alterar o comando de execução do Blat. Esse ponto de customização foi criado para atender as necessidades dos clientes que precisam informar informações específicas do seu serviço de e-mail, que não são contempladas pelos produtos Datasul.
A API tem algumas restrições ao ser comparado a um serviço de e-mail, ela não faz validações dos tipos de arquivos anexados a mensagem, nem outros tipos de tratamento que um serviço de e-mail realiza. Caso ocorra alguma destas validações que a API não trata, será tratado pela API que todos os e-mails foram enviados corretamente.
Caso houver algum erro no envio do e-mail, o remetente receberá um e-mail do serviço de e-mail, que a mensagem não pode ser enviada ao destinatário.
Em Agosto de 2012 foi incluído uma nova forma de envio de e-mail, que é utilizando a aplicação JAVA. Essa funcionalidade não está disponível para os envios padrões do produto. Essa funcionalidade só pode ser utilizada com programas específicos que utilizarem a API. No decorrer desta documentação serão detalhados os procedimentos para utilização.
Em Junho de 2013 foi disponibilizado o envio de e-mail com SSL que utiliza o programa MailSend que é freeware. Esse programa envia e-mails via protocolo SMTP e encontra-se no diretório (interfac/mail). Essa funcionalidade não esta disponível para os envios padrões do produto. Essa funcionalidade só pode ser utilizada com programas específicos que utilizarem a API. No decorrer desta documentação serão detalhados os procedimentos para utilização.

Temp-tables

...

tt-envio2

Possui definições da mensagem a ser enviada.

Atributo	Tipo	Valor Inicial	Descrição
versao-integracao	integer		Versão de integração da API.
servidor	character		Hostname ou endereço IP do servidor de e-mail. Se não informado, é utilizado o cadastro dos parâmetros de e-mail do produto.
porta	integer	0	Número da Porta do servidor de e-mail. Se não informado, é utilizado o cadastro dos parâmetros globais do produto. Só influencia quando utilizado OCX para envio da mensagem.
exchange	logical	no	Utilizar servidor Exchange para envio da mensagem.
destino	character		Destinatário(s) da mensagem. Quando é mais de um, devem ser separados por vírgulas. Deve ser informado obrigatoriamente. Quando for utilizado para envio de fax, deve ser passada a inicial “[fax:número]”.
copia	character		Cópia Carbono da mensagem. Quando é mais de um, devem ser separados por vírgulas. Para ambiente UNIX, os endereços adicionados neste campo serão incluídos no campo "para".
remetente	character		Remetente da mensagem. Só influencia quando utilizado OCX para envio da mensagem. Precisa ter os padrões de um endereço de e-mail([email protected]). Tem que ser um e-mail valido quando utilizado JAVA.
assunto	character		Assunto da mensagem.
mensagem	character		Corpo da mensagem. Informação obrigatória.
arq-anexo	character		Caminho completo do arquivo a ser anexado na mensagem. Disponível apenas para envio de mensagem através de MS-Exchange, Blat, Java e UNIX. Em outros casos, é incorporado na mensagem, o caminho do arquivo. Para anexar mais de um arquivo os mesmos devem ser separados por virgula.
importancia	integer	0	Nível da importância da mensagem. Só influencia quando utilizado servidor Exchange. Os valores possíveis são de 0 a 2: 0 – Prioridade Baixa, 1 – Prioridade Normal, 2 – Prioridade Alta.
log-enviada	logical	no	Envia uma mensagem para o remetente assim que a sua mensagem original for enviada. Só influencia quando utilizado servidor Exchange.
log-lida	logical	no	Envia uma mensagem para o remetente assim que a sua mensagem original for lida. Só influencia quando utilizado servidor Exchange.
acomp	logical	yes	Execução do utilitário ut-acomp, para verificar o desenvolvimento da execução. Só influencia quando utilizado servidor Exchange.
formato	character	Texto	Aceita dois valores: "TEXTO", para enviar e-mail sem formatação e "HTML" , onde o e-mail será enviado no formato HTML.

Abaixo é possível visualizar onde cada atributo é obrigatório ou opcional:

Atributo	EXCHANGE	FAX	BLAT/OCX	SENDMAIL (UNIX)	JAVA	MAILSEND (SSL)
versao-integracao	Obrigatório	Obrigatório	Obrigatório	Obrigatório	Obrigatório	Obrigatório
servidor	Desnecessário	Desnecessário	Opcional	Opcional	Obrigatório	Obrigatório
porta	Desnecessário	Desnecessário	Opcional	Desnecessário	Obrigatório	Obrigatório
destino	Obrigatório	Obrigatório	Obrigatório	Obrigatório	Obrigatório	Obrigatório
copia	Opcional	Opcional	Opcional	Desnecessário	Desnecessário	Opcional
remetente	Desnecessário	Desnecessário	Obrigatório	Opcional	Obrigatório	Obrigatório
assunto	Opcional	Opcional	Obrigatório	Opcional	Obrigatório	Obrigatório
mensagem	Obrigatório	Obrigatório	Obrigatório	Obrigatório	Obrigatório	Obrigatório
arq-anexo	Opcional	Obrigatório	Opcional¹	Opcional³	Opcional	Opcional
importancia	Opcional	Desnecessário	Desnecessário	Desnecessário	Desnecessário	Desnecessário
log-enviada	Opcional	Desnecessário	Desnecessário	Desnecessário	Desnecessário	Desnecessário
log-lida	Opcional	Desnecessário	Desnecessário	Desnecessário	Desnecessário	Desnecessário
acomp	Opcional	Desnecessário	Desnecessário	Desnecessário	Desnecessário	Desnecessário
formato	Opcional²	Desnecessário	Opcional¹	Opcional³	Desnecessário	Desnecessário

1 - Utilização do Blat. É necessário encontrar o arquivo “interfac/mail/blat.exe” na estrutura de diretórios do produto. Caso não seja encontrado, o e-mail será enviado sem o anexo. O arquivo “blat.exe” é distribuído gratuitamente junto às mídias/pacotes dos produtos Datasul.

2 - Devido a limitações técnicas, só é possível enviar e-mail no formato HTML utilizando Outlook 2000 ou posterior.

3 - Devido a limitações técnicas, não é possível enviar e-mail no formato HTML quando existir arquivo anexo no UNIX.

tt-mensagem

Possui o conteúdo da mensagem enviada. Essa temp-table foi criada porque o número máximo de caracteres por registro no Progress é de 32kb e se a mensagem do e-mail possuísse mais 32 Kb acontecia o erro Progress 444. Com essa temp-table será possível enviar e-mail com quantos caracteres forem necessários, menos com a opção Exchange que ainda mantém esta limitação.

Atributo	Tipo	Valor Inicial	Descrição
seq-mensagem	integer		Sequência da mensagem
mensagem	character		Conteúdo da mensagem

tt-erro

Possui os erros encontrados pela API.

Atributo	Tipo	Descrição
cod-erro	integer	Número do erro
desc-erro	character	Descrição do erro
desc-arq	character	Caminho do arquivo que não pode ser anexado, por se tratar de envio de mensagem no ambiente UNIX.

tt-paramEmail

Indica tipo de envio de e-mail.

Atributo	Tipo	Valor Inicial	Descrição
caminhoEmail	integer	1	Esta campo pode receber os seguintes valores: 0-Unix 1-Blat 2-Exchange 3-Java 4-MailSend (SSL) *** Se for atribuído um valor diferente destes, o valor padrão será BLAT

Execução

...

A API irá executar duas validações básicas:

Versão de integração: verifica se o programa chamador está íntegro com a API, e isto ocorre através da verificação da versão de integração passada como parâmetro. Caso a versão esteja incompatível, a API abortará a execução retornando o código de erro 3941.
Inconsistência ou insuficiência de dados: verifica a inconsistência e/ou insuficiência dos dados. Isto ocorre através da verificação dos dados passados como parâmetros. Caso os dados sejam inconsistentes ou insuficientes, a API abortará a execução retornando o código de erro 8646. Cabe ao programa de origem, verificar a consistência do registro que está sendo enviado.

Existem dois retornos possíveis para a execução da API:

OK: Mensagem enviada com sucesso.
NOK: Envio de mensagem abortado. Os erros encontrados serão retornados através da temp-table tt-erros.

Exemplos

...

Bloco de código

title	Fax
linenumbers	true

{utp/utapi019.i}
RUN utp/utapi019.p PERSISTENT SET h-utapi019.
CREATE tt-envio2.
ASSIGN tt-envio2.versao-integracao = 1
       tt-envio2.destino     = "[fax:0,0474417020]"   
       tt-envio2.assunto     = "xxxxxxxxxx"      
       tt-envio2.arq-anexo   = "c:/tmp/api-fax.doc".

CREATE tt-mensagem.
ASSIGN tt-mensagem.seq-mensagem = 1
       tt-mensagem.mensagem = "Mensagem 1".

CREATE tt-mensagem.
ASSIGN tt-mensagem.seq-mensagem = 2
       tt-mensagem.mensagem = "Mensagem 2".

OUTPUT TO VALUE(SESSION:TEMP-DIRECTORY + "envemail.txt").
    RUN pi-execute2 IN h-utapi019(INPUT TABLE tt-envio2,
                                  INPUT TABLE tt-mensagem,
                                  OUTPUT TABLE tt-erros).
OUTPUT CLOSE.
 
IF RETURN-VALUE = "NOK" THEN DO:
    FOR EACH tt-erros:
        DISPLAY tt-erros WITH 1 COLUMN WIDTH 300.
    END.
END.

DELETE PROCEDURE h-utapi019.

Observações:

Para o envio de FAX, é necessário que esteja instalado algum software client de envio de FAX.
Quando a API de envio de FAX/MAIL for utilizada para envio de FAX, o campo tt-envio2.destino deve seguir a seguinte sintaxe – “[fax:número]”.
Caso haja a necessidade de se enviar mais de 32kb de texto, a mensagem que será apresentada no FAX, deve estar dentro do arquivo anexo.

Bloco de código

title	E-mail - BLAT
linenumbers	true

{utp/utapi019.i}
RUN utp/utapi019.p PERSISTENT SET h-utapi019.
CREATE tt-envio2.
ASSIGN tt-envio2.versao-integracao = 1
       tt-envio2.servidor    = "172.16.1.80"
       tt-envio2.porta       = 25
       tt-envio2.destino     = "[email protected],[email protected]"
       tt-envio2.remetente   = "[email protected]"
       tt-envio2.assunto     = "subject"
       tt-envio2.arq-anexo   = "c:/tmp/texto.doc"
       tt-envio2.formato     = "HTML".
CREATE tt-mensagem.
ASSIGN tt-mensagem.seq-mensagem = 1
       tt-mensagem.mensagem     = "<h1><center>message body 1</pre>".
CREATE tt-mensagem.
ASSIGN tt-mensagem.seq-mensagem = 2
       tt-mensagem.mensagem     = "<h1><center>message body 2</pre>".
OUTPUT to value(SESSION:TEMP-DIRECTORY + "envemail.txt"). 
    RUN pi-execute2 IN h-utapi019 (INPUT  table tt-envio2,
                                   INPUT  table tt-mensagem,
                                   OUTPUT table tt-erros).
OUTPUT close.
       
IF  RETURN-VALUE = "NOK" THEN DO:
    FOR EACH tt-erros:
        DISP tt-erros WITH 1 COLUMN WIDTH 300.
    END. 
END.
DELETE PROCEDURE h-utapi019.

Observações:

Campo "exchange" retirado da tt-envio2, pois valor inicial é "no".
Campo "remetente" é obrigatório e deve ter um valor válido.
Campo "copia" é opcional.
Temp-table tt-paramEmail não é necessária, pois valor padrão do envio de e-mail é o BLAT.

Bloco de código

title	E-mail - JAVA

{utp/utapi019.i1}
RUN utp/utapi019.p PERSISTENT SET h-utapi019.
CREATE tt-envio2.
ASSIGN tt-envio2.versao-integracao = 1
       tt-envio2.servidor    = "172.16.1.80"
       tt-envio2.porta       = 25
       tt-envio2.destino     = "[email protected],[email protected]"
       tt-envio2.remetente   = "[email protected]"
       tt-envio2.assunto     = "subject"
       tt-envio2.arq-anexo   = "c:/tmp/texto.doc"
       tt-envio2.formato     = "HTML".
CREATE tt-mensagem.
ASSIGN tt-mensagem.seq-mensagem = 1
       tt-mensagem.mensagem     = "<h1><center>message body 1</pre>".
CREATE tt-mensagem.
ASSIGN tt-mensagem.seq-mensagem = 2
       tt-mensagem.mensagem     = "<h1><center>message body 2</pre>".
CREATE tt-paramEmail.
ASSIGN tt-paramEmail.caminhoEmail = 3. /*0-Unix,1-Blat,2-Exchange,3-Java,4-MailSend*/
OUTPUT to value(SESSION:TEMP-DIRECTORY + "envemail.txt"). 
    RUN pi-execute3 IN h-utapi019 (INPUT  table tt-envio2,
                                   INPUT  table tt-mensagem,
                                   INPUT  table tt-paramEmail,
                                   OUTPUT table tt-erros).
OUTPUT close.
       
IF  RETURN-VALUE = "NOK" THEN DO:
    FOR EACH tt-erros:
        DISP tt-erros WITH 1 COLUMN WIDTH 300.
    END. 
END.
DELETE PROCEDURE h-utapi019.

Árvore de páginas

Versões comparadas

Versão antiga 1

Nova versão 2

Chave

Temp-tables

tt-envio2

tt-mensagem

tt-erro

tt-paramEmail

Execução

Exemplos

Árvore de páginas

Histórico da Página

Versões comparadas

Versão antiga 1

Nova versão 2

Chave

Temp-tables

tt-envio2

tt-mensagem

tt-erro

tt-paramEmail

Execução

Exemplos