Índice

Objetivo

Utilização da API utapi019 para envio de mensagens pelo servidor de correio eletrônico..

Fontes

$/FOUNDATION/Fontes_Doc/Sustentacao/V11/V11/progress/src/utp

utapi019.p
utapi019.i
utapi019.i1
utapi019.i2

Considerações gerais

Parâmetros de e-mail

O produto possui um cadastro de parâmetros de e-mail (BTB962ZB). Mais informações quanto a parametrização estão disponíveis em: Parâmetros Email Foundation (BTB962ZB).

Esses parâmetros serão utilizados quando não informados na temp-table enviada à API:

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. Caso 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. Caso 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.
copia	character		Cópia Carbono da mensagem. Quando é mais de um, devem ser separados por vírgulas. Para ambiente UNIX, os endereços adicionados nesse 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 por MS-Exchange, Blat, Java e UNIX. Em outros casos, é incorporado na mensagem, o caminho do arquivo. Para anexar mais de um arquivo, eles 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	Datasul Mail Service	EXCHANGE	BLAT/OCX	SENDMAIL (UNIX)	JAVA	MAILSEND (SSL)
versao-integracao	Obrigatório	Obrigatório	Obrigatório	Obrigatório	Obrigatório	Obrigatório
servidor	Opcional	Desnecessário	Opcional	Opcional	Obrigatório	Obrigatório
porta	Opcional	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	Opcional⁴	Desnecessário	Obrigatório	Opcional	Obrigatório	Obrigatório
assunto	Obrigatório	Opcional	Obrigatório	Opcional	Obrigatório	Obrigatório
mensagem	Obrigatório	Obrigatório	Obrigatório	Obrigatório	Obrigatório	Obrigatório
arq-anexo	Desnecessário⁵	Opcional	Opcional¹	Opcional³	Opcional	Opcional
importancia	Desnecessário	Opcional	Desnecessário	Desnecessário	Desnecessário	Desnecessário
log-enviada	Desnecessário	Opcional	Desnecessário	Desnecessário	Desnecessário	Desnecessário
log-lida	Desnecessário	Opcional	Desnecessário	Desnecessário	Desnecessário	Desnecessário
acomp	Desnecessário	Opcional	Desnecessário	Desnecessário	Desnecessário	Desnecessário
formato	Opcional	Opcional²	Opcional¹	Opcional³	Desnecessário	Desnecessário

Importante

Para 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 não será enviado. O arquivo blat.exe é distribuído gratuitamente junto às mídias/pacotes dos produtos Datasul.
Só é possível configurar servidor Exchange Outlook 2000 ou posterior.
Não é possível enviar e-mail no formato HTML quando existir arquivo anexo no UNIX.
Campo utilizado para a funcionalidade Responder Para
Par envio de anexos via Datasul Mail Service deve ser utilizada a tabela ttAttachment.

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 caso a mensagem do e-mail possuísse mais 32 Kb era exibida a mensagem 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 essa limitação.

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

ttAttachment

Possui informações dos arquivos que serão anexos ao e-mail.

Atributo	Tipo	Descrição
fileName	Character	Nome do arquivo
fileType	Character	Tipo de arquivo em formato MIME type. Se não for informado, o valor será definido de acordo com a extensão do arquivo.
fileContent	Blob	Conteúdo do arquivo em formato binário

O envio de anexos via Datasul Mail Service funciona somente através da tabela ttAttachment.

A tabela pode ser utilizada também para os outros métodos de envio.

tt-paramEmail

Indica somente o tipo de envio de e-mail (campo caminhoEmail) e sua evolução segue na definição da TempTable tt-paramEmail2, abaixo.

tt-paramEmail2

A include utapi019.i2 contempla a Definição da TempTable tt-paramEmail2 como forma de evolução da api utapi019, de modo a seguir o Guia TOTVS de Implementação de APIs.

Indica tipo de envio de e-mail, usuário e senha para autenticação no servidor de e-mail caso venha a ser necessário, opção de ativar comportamento de resposta do para utilização de remetente padrão.

Atributo	Tipo	Valor Inicial	Descrição
caminhoEmail	integer	1	Esse campo pode receber os seguintes valores: 0-Unix 1-Blat 2-Exchange 3-Java 4-MailSend (SSL) 5-Datasul Mail Service Caso for atribuído um valor diferente desses, o valor padrão será BLAT
mailUser	character		Código do usuário para autenticação (se necessário)
mailPass	character		Senha do usuário para autenticação (se necessário)
TLS	logical	no	Protocolo - Apenas para Datasul Mail Service
SSL	logical	no	Protocolo - Apenas para Datasul Mail Service
Debug	logical	no	Ativa o debug para o servidor de aplicação
remetente	logical	no	Remetente do envio de e-mail
ativaRemetPadrao (*)	logical	no	Ativa o comportamento "Responder Para" (*)
codRemetPadrao (*)	character		Código (e-mail) do remetente que ira receber a resposta, caso o campo logico ativaRemetPadrao estiver como yes (*)

Os parâmetros acima (tt-paramEmail2) não são obrigatórios, caso não sejam informados, serão utilizadas as informações da tela de parâmetros de e-mail do foundation (btb962zb).

Importante:

(*) Estes dois campos só funcionam com o tipo de envio de e-mail Datasul Mail Service. Os mesmo foram incluídos na release 12.1.23.

Atenção:

Para execução do programa de teste do Datasul Mail Service na release 12.1.29 o supra citado deverá ser compilado, ou, deve possuir no propath a include prgvers.i, nesta versão ainda existia um pré-processador de versão que é utilizado em tempo de compilação, o progress na execução de um código no editor realiza a compilação para realizar a execução, desta forma, se o programa de exemplo for compilado, ou, existir a include no propath o erro de "O parâmetro identificador de temp-table tt-paramEmail2 não confere com a temp-table destino tt-paramEmail2. (5363)" não irá ocorrer.

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.

Funcionalidade Responder Para

A funcionalidade Responder Para serve foi criada para que a resposta do e-mail seja direcionada para um endereço diferente do que o utilizado para o envio, por exemplo, equipes de marketing. Caso a função seja ativada, a resposta ao e-mail será enviada ao valor informado no campo "remetente" da tabela tt-envio2. Caso este campo não esteja preenchido, será utilizado o remetente informado no cabeçalho do e-mail. Para decisão do remetente do e-mail enviado será utilizada a seguinte estrutura:

campo "codRemetPadrao" da tabela tt-paramEmail2;
campo "Remetente Padrão" da tela Parâmetros Email Foundation (BTB962ZB);
campo "remetente" da tabela tt-envio2.

Execução

A API possui um método que pode ser executado:

pi-execute4: recebe cinco temp-tables como parâmetros: tt-envio2 (INPUT), tt-mensagem (INPUT), tt-paramEmail (INPUT), ttAttachment (INPUT) e tt-erros (OUTPUT).

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 por meio 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 a mensagem 3941.
Inconsistência ou insuficiência de dados: verifica a inconsistência e/ou insuficiência dos dados. Isto ocorre por meio 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 por meio da temp-table tt-erros.

Exemplos

Atenção

Para correto funcionamento dos exemplos, os mesmo devem ser compilados antes da execução

Datasul Mail Service

{utp/utapi019.i2}

RUN utp/utapi019.p PERSISTENT SET h-utapi019.

CREATE tt-envio2.
ASSIGN tt-envio2.versao-integracao = 1
       tt-envio2.destino   = "[email protected]"	
	   tt-envio2.remetente = "[email protected]"
	   tt-envio2.assunto   = "teste envio DATASUL MAIL SERVICE".

CREATE ttAttachment.
ASSIGN ttAttachment.fileName    = "teste.txt"
       ttAttachment.fileType    = "text/plain".

// COPIANDO CONTEÚDO DE ARQUIVO DO COMPUTADOR PARA O CAMPO BLOB
COPY-LOB FILE "C:\teste.txt" TO ttAttachment.fileContent.   //conteúdo do arquivo em formato binário


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".

CREATE tt-paramEmail2.
ASSIGN tt-paramEmail2.caminhoEmail = 5.

RUN pi-execute4 in h-utapi019(INPUT  TABLE tt-envio2,
                              INPUT  TABLE tt-mensagem,
							  INPUT  TABLE tt-paramEmail2,
							  INPUT  TABLE ttAttachment,
							  OUTPUT TABLE tt-erros).

IF RETURN-VALUE = "NOK" THEN DO:
    FOR EACH tt-erros:
        DISP
			tt-erros WITH 1 COLUMN WIDTH 300.
    END.
END.
ELSE
    MESSAGE "OK" VIEW-AS ALERT-BOX.

DELETE PROCEDURE h-utapi019.

Observações:.

1) Os valores para os campos mensagem, importancia, log-enviada, log-lida e acomp podem ser desconsiderados na tabela tt-envio2 porque não influenciarão no funcionamento.

2) Os valores para os campos servidor e porta são opcionais para a tabela tt-envio2. Caso não sejam informados, serão utilizados os valores cadastrados nos parâmetros de e-mail.

3) Os valores para os campos mailUser, mailPass, TLS, SSL, debug, ativaRemetPadrao e codRemetPadrao podem ser desconsiderados na tabela tt-paramEmail2 porque não influenciarão no funcionamento.

4) Não é necessário popular a temp-table tt-paramEmail2 com dados, porém é obrigatório sua definição.

E-mail - BLAT

{utp/utapi019.i2}

RUN utp/utapi019.p PERSISTENT SET h-utapi019.

CREATE tt-envio2.
ASSIGN tt-envio2.versao-integracao = 1
	   tt-envio2.servidor          = "servidor"
       tt-envio2.porta             = 999
	   tt-envio2.exchange          = FALSE
	   tt-envio2.destino           = "destino@dominio"
	   tt-envio2.remetente         = "remetente@dominio"
	   tt-envio2.assunto           = "teste envio BLAT"
	   tt-envio2.arq-anexo         = "XXXXX".

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".

CREATE tt-paramEmail2.
ASSIGN tt-paramEmail2.caminhoEmail = 1.

RUN pi-execute4 in h-utapi019(INPUT  TABLE tt-envio2,
							  INPUT  TABLE tt-mensagem,
							  INPUT  TABLE tt-paramEmail2,
							  INPUT  TABLE ttAttachment,
							  OUTPUT TABLE tt-erros).

IF RETURN-VALUE = "NOK" THEN DO:
    FOR EACH tt-erros:
        DISP tt-erros WITH 1 COLUMN WIDTH 300.
    END.
END.
ELSE
    MESSAGE "OK" VIEW-AS ALERT-BOX.

DELETE PROCEDURE h-utapi019.

Observações:.

1) Os valores para os campos mensagem, importância, log-enviada, log lida e acomp podem ser desconsiderados na tabela tt-envio2 porque não influenciarão no funcionamento.

2) Os valores para os campos mailUser, mailPass, TLS, SSL, debug, ativaRemetPadrao e codRemetPadrao podem ser desconsiderados na tabela tt-paramEmail2 porque não influenciarão no funcionamento.

3) Não é necessário popular a temp-table tt-paramEmail2 com dados, porém é obrigatório sua definição.

MS-Exchange

{utp/utapi019.i2}

RUN utp/utapi019.p PERSISTENT SET h-utapi019.


CREATE tt-envio2.
ASSIGN tt-envio2.versao-integracao = 1
	   tt-envio2.destino           = "destino@dominio"
	   tt-envio2.assunto           = "teste envio EXCHANGE"
	   tt-envio2.arq-anexo         = "XXXXX"
	   tt-envio2.importancia       = 1
	   tt-envio2.log-enviada       = TRUE
	   tt-envio2.log-lida          = TRUE.

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".


CREATE tt-paramEmail2.
ASSIGN tt-paramEmail2.caminhoEmail = 2.
 
RUN pi-execute4 in h-utapi019(INPUT  TABLE tt-envio2,
                              INPUT  TABLE tt-mensagem,
                              INPUT  TABLE tt-paramEmail2,
                              INPUT  TABLE ttAttachment,
                              OUTPUT TABLE tt-erros).

IF RETURN-VALUE = "NOK" THEN DO:
    FOR EACH tt-erros:
        DISP tt-erros WITH 1 COLUMN WIDTH 300.
    END.
END.
ELSE
    MESSAGE "OK" VIEW-AS ALERT-BOX.


DELETE PROCEDURE h-utapi019.

Observações:.

1) Os valores para os campos servidor, porta, remetente e mensagem podem ser desconsiderados na tabela tt-envio2 porque não influenciarão no funcionamento.

2) Os valores para os campos mailUser, mailPass, TLS, SSL, debug, ativaRemetPadrao e codRemetPadrao podem ser desconsiderados na tabela tt-paramEmail2 porque não influenciarão no funcionamento.

3) Não é necessário popular a temp-table tt-paramEmail2 com dados, porém é obrigatório sua definição.

4) Os campos importancia, log-enviada, log-lida e acomp só influem neste tipo de execução e são opcionais.

Pontos de customização

A API possui eventos de UPC que permitem ao usuário alterar o comando de execução. Esses pontos foram desenvolvidos para atender as necessidades de usuários que precisam adicionar informações específicas não contempladas no produto Datasul.

OBS:

A partir da versão 12.1.7, não é mais necessário alterar a linha de comando para adição de usuário e senha, a autenticação é feita por meio dos dados informados nos parâmetros.

Exemplo de UPC - BLAT

{include/i-epc200.i1} /* definição da temp-table tt-epc */

DEFINE INPUT        PARAMETER p-ind-event AS CHARACTER NO-UNDO.
DEFINE INPUT-OUTPUT PARAMETER TABLE       FOR tt-epc.

DEFINE VARIABLE cComandoEmail AS CHARACTER NO-UNDO.

IF p-ind-event = "eMailBlat" THEN DO:
    FIND FIRST tt-epc
        WHERE tt-epc.cod-event     = "eMailBlat":U
        AND   tt-epc.cod-parameter = "CommandEmail":U
        EXCLUSIVE-LOCK NO-ERROR.
    IF AVAILABLE tt-epc THEN 
        ASSIGN cComandoEmail = tt-epc.val-parameter.
    
    ASSIGN cComandoEmail = cComandoEmail + " -hostname ~"tech-valdir~"":U.

    IF AVAILABLE tt-epc THEN 
        ASSIGN tt-epc.val-parameter = cComandoEmail.
END.

O nome do evento pode possuir os seguintes valores:

eMailUnix: evento para customização de envio em UNIX (tt-paramEmail.caminhoEmail = 0);
eMailBlat: evento para customização de envio via BLAT (tt-paramEmail.caminhoEmail = 1);
SaveEmail: evento para customização de envio via Exchange (tt-paramEmail.caminhoEmail = 2);
eMailJava: evento para customização de envio via JAVA (tt-paramEmail.caminhoEmail = 3);
eMailSend: evento para customização de envio via MailSend (tt-paramEmail.caminhoEmail = 4).

Árvore de páginas

Utilização de API de envio de e-mail

Objetivo

Fontes

Considerações gerais

Parâmetros de e-mail

Temp-tables

tt-envio2

tt-mensagem

ttAttachment

tt-paramEmail

tt-paramEmail2

tt-erro

Funcionalidade Responder Para

Execução

Exemplos

Pontos de customização