Class: Email

@nginstack/engine/lib/email/Email~ Email


new Email()

Classe responsável pelo envio de e-mails no sistema.

O servidor SMTP que será utilizado no envio de e-mails é determinado pela propriedade #smtpServer. Nela pode ser informada a chave de um servidor SMTP cadastrado na classe de dados "/Dados/Sistema/Serviços/Servidores SMTP" (-1898146235) ou uma string contendo o endereço de rede e porta do servidor SMTP no formato "address:port". Caso ela não seja informada, será utilizado o servidor SMTP padrão configurado no sistema.

Se não houver necessidade de direcionar determinados e-mails para um servidor SMTP específico de saída, é recomendado que sempre seja utilizado o servidor padrão e as propriedades #smtpServer, #securityMode, #senderEmailAddress, #userName e #password não sejam preenchidas. A propriedade #senderName pode opcionalmente ser preenchida caso se deseje indicar um nome de remetente diferente do padrão com o objetivo de identificar melhor a origem ou o motivo dos e-mails. Alguns servidores SMTP podem ignorar esta propriedade e sempre utilizar o nome do usuário associado à conta SMTP utilizada.

Examples
// Exemplo utilizando a configuração padrão do sistema
const email = new Email();
email.addRecipient('Nome destinatário', 'usuario@exemplo.com.br');
email.subject = 'Teste de envio de e-mail';
email.htmlContent = '<b>Olá mundo.</b>';
email.send();
// Exemplo utilizando um servidor SMTP específico
const email = new Email();
email.smtpServer = smtpServerKey;
email.addRecipient('Nome destinatário', 'usuario@exemplo.com.br');
email.subject = 'Teste de envio de e-mail';
email.htmlContent = '<b>Olá mundo.</b>';
email.send();
// Exemplo utilizando um servidor SMTP não cadastrado no sistema
const email = new Email();
email.smtpServer = 'smtp.gmail.com:465';
email.securityMode = 'smtps';
email.userName = 'sistema@empresa.com.br';
email.password = 'password';
email.senderName = 'Nome do remetente';
email.senderEmailAddress = 'sistema@empresa.com.br';
email.addRecipient('Nome destinatário', 'usuario@exemplo.com.br');
email.subject = 'Teste de envio de e-mail';
email.htmlContent = '<b>Olá mundo.</b>';
email.send();

Members


autoTls :boolean

Se o valor for true, será realizado automaticamente o upgrade para um canal seguro SSL/TLS desde que o servidor SMTP suporte.

Type:
  • boolean
Deprecated:
  • Utilize a propriedade `securityMode`.

content :string

Conteúdo do e-mail.

Type:
  • string

fullSsl :boolean

Se o valor for true, estabelece um canal seguro SSL/TLS assim que estabelece a conexão.

Type:
  • boolean
Deprecated:
  • Utilize a propriedade `securityMode`.

htmlContent :string

Conteúdo do e-mail no formato HTML.

Type:
  • string

log :string

Propriedade descontinuada que sempre retornará uma string vazia. Os logs devem ser lidos no Engine responsável pelo envio ou na tabela de log transacional (iLog).

Type:
  • string

logEnabled :boolean

Propriedade descontinuada. Os logs sempre são gerados e gravados no Engine responsável pelo envio e na tabela de log transacional (iLog).

Type:
  • boolean

password :string

Senha do remetente no servidor de SMTP.

Type:
  • string

replyToAddress :string

Endereço de e-mail para o qual o destinatário deve enviar a resposta desta mensagem.

Type:
  • string

securityMode :string

Modo de segurança utilizado no envio do e-mail para o servidor SMTP. Valores possíveis: 'insecure', 'starttls' e 'smtps'.

Type:
  • string

senderEmailAddress :string

Endereço de e-mail do remetente. Caso não seja informado, será utilizado o endereço do remetente padrão associado à conta SMTP.

Importante: alguns servidores SMTP podem ignorar esta configuração e sempre enviar o email utilizando o endereço associado à conta SMTP utilizada. Caso esteja sendo utilizada uma conta SMTP cadastrada no sistema, o endereço informado também pode ser ignorado caso a opção "Forçar remetente padrão" esteja habilitada.

Type:
  • string

senderName :string

Nome do remetente. Caso não seja informado, será utilizado o nome do remetente padrão associado à conta SMTP.

Importante: alguns servidores SMTP podem ignorar esta configuração e sempre enviar o email utilizando o nome associado à conta SMTP utilizada. Caso esteja sendo utilizada uma conta SMTP cadastrada no sistema, o nome informado também pode ser ignorado caso a opção "Forçar remetente padrão" esteja habilitada.

Type:
  • string

smtpServer :DBKey|number|string

Servidor SMTP que deve ser utilizado para enviar este e-mail. Caso esta propriedade não seja preenchida, será utilizado o servidor SMTP padrão configurado na base de dados, caso haja um.

Pode ser informada a chave de um servidor SMTP configurado na classe de dados "Servidores SMTP" (-1898146235) ou o nome ou endereço IP do servidor no formato "address:port".

Ao informar a chave de um servidor SMTP configurado na base de dados, as propriedades securityMode, senderName, senderEmailAddress, userName e password são configuradas com base nas configurações cadastradas do servidor SMTP. Essa configuração automática não ocorre quando é informado o nome de rede ou endereço IP de um servidor SMTP. Nesse caso, essas propriedades precisam ser informadas adequadamente para que o envio possa ser realizado.

Type:
  • DBKey | number | string

subject :string

Assunto do e-mail.

Type:
  • string

userName :string

Nome de usuário do remetente no servidor de SMTP.

Type:
  • string

Methods


<static> encryptSmtpPassword(smtpServer, password)

Criptografa a senha do servidor SMTP a fim de permitir que ela possa ser gravada no cadastro de servidores SMTP da base de dados com um nível adicional de segurança.

Importante: este método permite a gravação de senhas na base de dados com um maior nível de segurança, no entanto essa segurança não deve ser considerada inviolável. Por esse motivo, as credenciais do servidor SMTP devem ser únicas para o sistema e não devem ser compartilhadas com outros serviços. Elas também devem ser renovadas periodicamente.

Parameters:
Name Type Description
smtpServer DBKey | number

Chave do cadastro do servidor SMTP na base de dados.

password string

Senha no servidor SMTP. A senha informada deve ter no máximo 256 caracteres.

Returns:

Senha criptografada. A senha criptografada retornada possui um tamanho superior ao da senha informada e deve ser esperada uma string de até 512 caracteres. Os dados retornados são codificados em Base85 e podem ser gravados diretamente em colunas textuais da base de dados sem a necessidade de codificações adicionais.

Type
string

<static> hasDefaultSMTPSettings()

Verifica se há um servidor SMTP configurado como padrão na base de dados.

Returns:

True se houver um servidor SMTP padrão configurado.

Type
boolean

addAttachment(name, content)

Adiciona um arquivo anexo ao e-mail.

Parameters:
Name Type Description
name string

Nome do arquivo anexo(Não precisa ser o nome original).

content string | ArrayBuffer

Conteúdo do arquivo anexo.


addRecipient(nameOrEmail [, email])

Adiciona um destinatário com apenas o e-mail, ou nome e e-mail.

Parameters:
Name Type Argument Description
nameOrEmail string

Nome ou email do destinatário.

email string <optional>

Endereço de email do destinatário, necessário somente se o mesmo não foi informado como o primeiro parâmetro.

Example
email.addRecipient('maria@exemplo.com.br');
email.addRecipient('Maria Silva','maria@exemplo.com.br');

addRecipientBcc(nameOrEmail [, email])

Adiciona um destinatário que receberá uma cópia oculta da mensagem (CCO).

Parameters:
Name Type Argument Description
nameOrEmail string

Nome ou Email do destinatário.

email string <optional>

Endereço de email do destinatário, necessário somente se o mesmo não foi informado como o primeiro parâmetro.

Example
email.addRecipientBcc('maria@exemplo.com.br');
email.addRecipientBcc('Maria Silva','maria@exemplo.com.br');

addRelatedContent(name, content)

Adiciona um arquivo no e-mail que poderá ser referenciado pelo corpo HTML.

O conteúdo adicionado deverá ser referenciado pelo Content-ID retornado por este método, conforme o exemplo a seguir.

Parameters:
Name Type Description
name string

Nome do conteúdo.

content string | ArrayBuffer

Conteúdo adicionado.

Returns:

Identificador único do conteúdo adicionado no e-mail. Será retornada uma string vazia se o tamanho do conteúdo for zero.

Type
string
Example
const content = virtualFS.getFileContent(key);
const cid = email.addRelatedContent(DBKey.from(key).str('iName'), content);
email.htmlContent = '<img src="cid:' + cid + '">';

clear()

Limpa os dados do e-mail.


send()

Envia o e-mail de acordo com configuração do servidor SMTP.

O e-mail será enviado a partir do Engine em execução caso ele seja um servidor ou se a propriedade "Enviar pelo servidor de aplicação" do servidor SMTP não estiver habilitada. Caso essa propriedade esteja ativa, o e-mail será encaminhado para o Engine servidor para que este possa encaminhar o e-mail para o servidor SMTP.

Este método se comportará de forma equivalente ao #sendLocally caso a propriedade #smtpServer esteja preenchida com o endereço de rede e a porta de um servidor SMTP.


sendLocally()

Envia o e-mail a partir do Engine corrente.

Importante: a partir da versão 71 do Engine é recomendado que os e-mails sempre sejam enviados pelo método send da classe Email. Esse método leva em consideração a configuração do servidor SMTP e redireciona automaticamente para o Engine servidor caso seja necessário.


write()

Escreve dados no conteúdo do e-mail e adiciona uma quebra de linha no final.