nginstack

Class: ImapClient

@nginstack/engine/lib/email/ImapClient~ ImapClient

new ImapClient(domain [, port])

Classe responsável pela leitura de mensagens de email utilizando o protocolo IMAP.

Esta classe possui métodos que leem e modificam nomes de caixas de entrada. Esses nomes podem possuir hierarquias, como se fossem pastas e subpastas, delimitadas por um separador definido pelo servidor (por exemplo, "/"). A descrição dos métodos que tratam das caixas de entrada fala em "hierarquias" e "separadores" para explicar seu comportamento.

Esta classe também possui métodos que referenciam emails a partir de conjuntos de identificadores. Os emails no protocolo IMAP são identificados por um número reutilizável, e portanto não-único, chamado "número de sequência". O servidor também pode implementar identificadores únicos para os emails. Todos os métodos que operam sobre as mensagens possuem uma versão que utiliza números de sequência (que nos referimos por messageId e idSet) e outra que utiliza identificadores únicos (uid e uidSet).

Um conjunto de números de sequência pode ser representado por um intervalo de números (como "5:50"), uma enumeração de números específicos, ou uma combinação de ambos, separados por vírgula (como "1:10,12,15"). O símbolo especial "" pode ser usado para representar o maior número de sequência na caixa de entrada. Um conjunto de UIDs é semelhante, mas não pode conter o símbolo especial "".

Parameters:
Name Type Argument Description
domain string

Servidor IMAP que deve ser utilizado para acessar os emails. Por exemplo, "imap.gmail.com" para o Gmail e "imap.outlook.com" para o Outlook.
port number <optional>

Porta usada para se conectar ao servidor IMAP. Esta classe sempre utiliza uma conexão TLS segura, cuja porta padrão é 993.
Example
const imapClient = new ImapClient('imap.gmail.com');
try {
  imapClient.login('nginstack@nginstack.com', appPasswd);
  imapClient.selectMailbox('Arquivos/XML');
  const ids = imapClient.search({ flags: ['unseen'] });
  const messages = imapClient.fetch(ids);
  messages.forEach(function (message) {
    const attachments = message.getAttachments();
    attachments
    .filter(function (attachment) {
      return attachment.contentType.indexOf('xml') !== -1;
    })
    .forEach(function (xmlFile) {
      console.log(xmlFile.textContent);
    });
  });
} finally {
  imapClient.logout();
}

Methods

authenticate(type, options)

Realiza autenticação do usuário no servidor IMAP.

Parameters:
Name Type Description
type AuthenticationType

Tipo de autenticação. São suportados "plain" e "xoauth2".
options PlainAuthentication | XOAuth2Authentication

Dados para autenticação. Varia de acordo com o tipo de autenticação.

copy(idSet, destinationMailbox)

Copia mensagens de uma caixa de entrada para outra.

Parameters:
Name Type Description
idSet string | number | Array.<number>

Conjunto de IDs de mensagens a serem copiadas. Pode ser um número, uma lista de números ou uma string com expressão suportada pelo protocolo IMAP.
destinationMailbox string

Caixa de entrada de destino.

createMailbox(mailbox)

Cria uma nova caixa de entrada no servidor IMAP.

Tentar criar uma caixa com "INBOX" ou um nome já existente resulta em erro.

Nomes terminados com o separador de hierarquia do servidor criam uma caixa de entrada sem o separador no final do nome. Separadores em quaisquer outros lugares do nome criam as caixas necessárias para que o nome seja válido. Por exemplo, "arquivos/trabalho/outros" também cria "arquivos/" e "arquivos/trabalho/" se ainda não existirem.

Parameters:
Name Type Description
mailbox string

Nome da nova caixa de entrada a ser criada.

deleteMailbox(mailbox)

Remove uma caixa de entrada no servidor IMAP.

Tentar remover "INBOX" ou uma caixa de entrada inexistente resulta em erro.

Este comando não remove nomes com hierarquia inferior. Por exemplo, remover "arquivos" não afetará "arquivos/trabalho".

Remover um nome que possui hierarquia inferior remove todas as mensagens daquela caixa de entrada e aplica o atributo "NoSelect", tornando aquela caixa não selecionável. Tentar remover nome que possui hierarquia inferior e já possui o atributo "NoSelect" resulta em erro.

Parameters:
Name Type Description
mailbox string

expunge()

Remove permanentemente da caixa de entrada corrente todas as mensagens marcadas com a flag "deleted" e retorna uma lista com os IDs das mensagens removidas.

Alguns servidores podem não implementar o fluxo de remoção de mensagens da maneira padrão, necessitando que a mensagem seja primeiro movida para uma caixa de entrada especial que funciona como lixeira, para só então ser marcada com a flag "deleted" e em seguida removida permanentemente com expunge.

Returns:

Lista de IDs das mensagens que foram removidas.

Type
Array.<number>

fetch(idSet [, query])

Faz o download de mensagens da caixa de entrada corrente.

Parameters:
Name Type Argument Description
idSet string | number | Array.<number>

Conjunto de IDs de mensagens a serem baixadas. Pode ser um número, uma lista de números ou uma string com expressão suportada pelo protocolo IMAP.
query string <optional>

Lista indicando quais dados serão baixados. Essa lista é composta por itens separados por espaço e, caso haja mais de um item, encapsulados entre parênteses.

Por padrão, a lista usada pelo método é (FLAGS UID INTERNALDATE RFC822.SIZE RFC822), que traz todos os dados suportados por este cliente e marca a mensagem como lida.

Os itens suportados por este cliente são:

  • BODY[]: Traz o corpo completo da mensagem, incluindo cabeçalho, e marca como lida.
  • BODY[HEADER]: Traz o cabeçalho da mensagem e marca como lida.
  • BODY.PEEK[] e BODY.PEEK[HEADER]: Trazem o corpo completo e o cabeçalho da mensagem, respectivamente, mas não marcam como lida.
  • RFC822 e RFC822.HEADER: Funcionalmente equivalentes a "BODY[]" e "BODY.PEEK[HEADER]", respectivamente.
  • INTERNALDATE: Traz a data de recebimento da mensagem.
  • RFC822.SIZE: Traz o tamanho da mensagem em octetos no formato RFC5322.
  • UID: Traz o unique ID da mensagem.
  • FLAGS: Traz as flags da mensagem, como "\Seen", "\Answered", "\Flagged", "\Deleted", "\Draft" ou "\Recent".
Returns:

Uma lista contendo as mensagens que foram baixadas. Independente da query, as mensagens baixadas sempre conterão messageId.

Cada mensagem é representada por um objeto que contém os seguintes dados:

  • messageId: O identificador da mensagem.
  • uid: O unique ID da mensagem.
  • size: O RFC822.SIZE da mensagem.
  • flags: A lista de flags da mensagem.
  • internalDate: A data de recebimento da mensagem.
  • subject: O assunto da mensagem.
  • to: O destinatário da mensagem.
  • from: O remetente da mensagem.
  • date: A data de envio da mensagem.
  • plainBody: O corpo da mensagem em texto simples.
  • htmlBody: O corpo da mensagem em HTML.
  • getAttachments: Função que retorna a lista de anexos da mensagem. Os anexos são retornados apenas se a query requisitar o corpo completo da mensagem.

Cada anexo é representado por um objeto que contém os seguintes dados:

  • filename: O nome do arquivo do anexo.
  • contentType: O tipo MIME do conteúdo do anexo.
  • textContent: O conteúdo do anexo em texto simples, caso o tipo do conteúdo seja textual.
  • data: O conteúdo do anexo em bytes.
Type
Array.<ImapEmail>
Example
// Baixar apenas os cabeçalhos de todas as mensagens e não marcar como lidas
imapClient.fetch('1:*', '(BODY.PEEK[HEADER])');

// Baixar o corpo das mensagens 10 e 15 no padrão RFC822.
imapClient.fetch([10, 15], 'RFC822')

// Baixar apenas o tamanho da mensagem 20
imapClient.fetch(20, 'RFC822.SIZE');

// Baixar o corpo das mensagens de 10 a 20 no padrão RFC822 e incluir o unique ID.
imapClient.fetch('10:20', '(RFC822 UID)')

// Baixar todos os dados da mensagem 15.
imapClient.fetch([15]);

listMailboxes( [referenceName] [, mailboxPattern])

Lista todas as caixas de entrada disponíveis no servidor IMAP e retorna uma lista de objetos, onde cada objeto contém informações sobre uma caixa de entrada.

Parameters:
Name Type Argument Description
referenceName string <optional>

Nome da referência da caixa de entrada. Indica que as caixas devem ser listadas a partir daquele nível hierárquico. Este método utiliza string vazia por padrão, que indica que todas as caixas devem ser listadas a partir da raiz.
mailboxPattern string <optional>

Padrão de correspondência para o nome da caixa de entrada. O caractere "" é um coringa que corresponde a qualquer sequência de zero ou mais caracteres naquela posição. O caractere "%" é semelhante, e corresponde a uma sequência de caracteres que não inclui o separador de hierarquia. Este método utiliza "" por padrão. Passar uma string vazia para este parâmetro retorna apenas o delimitador e a raiz da referência.
Returns:

Lista de caixas de entrada. Cada objeto contém informações sobre uma caixa de entrada. São elas:

  • name: o nome da caixa de entrada.
  • delimiter: o delimitador utilizado para hierarquia de caixas de entrada.
  • attributes: lista de atributos da caixa de entrada.
Type
Array.<Mailbox>

login(user, password)

Realiza login do usuário no servidor IMAP utilizando um nome de usuário e uma senha. Alguns servidores não aceitam autenticação via senha e exigem o uso de OAuth 2.0, como por exemplo o Outlook. Outros aceitam apenas uso de senhas de aplicativo, como é o caso do Gmail.

Usar o tipo "plain" com o método authenticate é mais recomendado, pois utiliza o comando "AUTHENTICATE" do protocolo IMAP, que é mais moderno. O método login deve ser usado apenas quando o servidor não suporta o comando "AUTHENTICATE".

Parameters:
Name Type Description
user string

Nome de usuário, geralmente o email.
password string

Senha do usuário.

logout()

Realiza logout do usuário no servidor IMAP, encerrando a sessão e permitindo a autenticação em outra conta utilizando o mesmo cliente.

O logout é realizado automaticamente quando o cliente é destruído pelo garbage collector. No entanto, caso seja necessário liberar recursos do servidor de forma mais eficiente, recomendamos que o logout seja antecipado manualmente.

move(idSet, destinationMailbox)

Move mensagens de uma caixa de entrada para outra.

Este método realiza uma cópia dos emails e apaga os originais. Caso falhe no meio da execução, alguns emails podem ficar na origem e outros no destino, mas os emails nunca serão duplicados.

O comando MOVE pode não ser suportado por alguns servidores.

Parameters:
Name Type Description
idSet string | number | Array.<number>

Conjunto de IDs de mensagens a serem movidas. Pode ser um número, uma lista de números ou uma string com expressão suportada pelo protocolo IMAP.
destinationMailbox string

Caixa de entrada de destino.

renameMailbox(oldName, newName)

Renomeia uma caixa de entrada no servidor IMAP.

Tentar renomear uma caixa de entrada que não existe, ou para um nome que já existe, resulta em erro.

Se o nome possui hierarquias inferiores, então elas também são renomeadas. Por exemplo, renomear "arquivos" para "dados" também renomeia "arquivos/trabalho" para "dados/trabalho".

Novos nomes que possuam separadores criam as caixas de entrada necessárias para que o nome seja válido. Por exemplo, renomear "arquivos/trabalho/outros" para "dados/trabalho/outros" também cria "dados/" e "dados/trabalho/" se ainda não existirem.

Renomear "INBOX" tem um comportamento especial. Esta operação move todos os emails de "INBOX" para a nova caixa de entrada com o nome especificado, deixando "INBOX" vazia. Se o servidor suporta nomes com hierarquia inferior a "INBOX", essas hierarquias não são afetadas.

Parameters:
Name Type Description
oldName string

Nome da caixa de entrada a ser renomeada.
newName string

Novo nome da caixa de entrada.

Busca mensagens na caixa de entrada corrente.

Parameters:
Name Type Description
query string | SearchOptions

Um comando suportado pelo protocolo IMAP ou um objeto de opções de busca. O comando cru proporciona uma maior flexibilidade na busca, enquanto o objeto apresenta uma interface estruturada e fácil de usar.

As opções de busca são:

  • since: Filtra mensagens recebidas após uma data específica. Pode ser uma instância de Date ou uma string no formato 'dd-Mon-yyyy'.
  • before: Filtra mensagens recebidas antes de uma data específica. Pode ser uma instância de Date ou uma string no formato 'dd-Mon-yyyy'.
  • subject: Filtra mensagens com um assunto específico.
  • from: Filtra mensagens de um remetente específico.
  • to: Filtra mensagens enviadas para um destinatário específico.
  • flags: Filtra mensagens com uma lista de flags específica.
Returns:

Uma lista contendo os IDs das mensagens que correspondem à busca.

Type
Array.<number>

selectMailbox(mailbox)

Seleciona uma caixa de entrada no servidor IMAP para que as mensagens nela possam ser acessadas. Na maioria dos servidores de email, a caixa de entrada padrão é chamada de "INBOX", e é onde os novos emails são entregues. Esta caixa é automaticamente selecionada no momento da autenticação.

Apenas uma caixa de entrada pode ser selecionada por vez. Para acessar simultaneamente outras caixas, é necessário criar uma nova instância do cliente IMAP.

No momento da seleção, a anterior é desfeita. Portanto, se a nova seleção falhar, o cliente passa a não possuir nenhuma caixa de entrada selecionada.

Parameters:
Name Type Description
mailbox string

Nome da caixa de entrada a ser selecionada.

store(idSet, query)

Altera o conjunto de flags das mensagens especificadas.

Parameters:
Name Type Description
idSet string | number | Array.<number>

Conjunto de IDs de mensagens a serem modificadas. Pode ser um número, uma lista de números ou uma string com expressão suportada pelo protocolo IMAP.
query string

Comando suportado pelo protocolo IMAP com as flags a serem modificadas.
Returns:

Uma lista contendo apenas as mensagens que foram atualizadas, mas sem nenhum dado do corpo da mensagem. Apenas messageId e flags. Caso o sufixo ".SILENT" seja usado, as mensagens não serão retornadas (mesmo que modificadas), resultando em uma lista vazia.

Type
Array.<ImapEmail>
Example
// Marcar mensagens 1, 3 e 5 como lidas.
imapClient.store([1, 3, 5], '+FLAGS (\\Seen)');

// Marcar mensagens de 2 a 10 como não lidas.
imapClient.store('2:10', '-FLAGS (\\Seen)');

// Sobrescrever as flags de todas as mensagens para lidas e respondidas e não retornar resposta.
imapClient.store('1:*', 'FLAGS.SILENT (\\Seen \\Answered )');

uidCopy(uidSet, destinationMailbox)

Copia mensagens de uma caixa de entrada para outra. Equivalente a copy, mas usando unique IDs.

Parameters:
Name Type Description
uidSet string | number | Array.<number>

Conjunto de UIDs de mensagens a serem copiadas. Pode ser um número, uma lista de números ou uma string com expressão suportada pelo protocolo IMAP.
destinationMailbox string

Caixa de entrada de destino.
See:

uidExpunge(uidSet)

Remove permanentemente da caixa de entrada corrente todas as mensagens marcadas com a flag "deleted" e cujo unique ID esteja presente no conjunto de UIDs especificado. Retorna uma lista com os UIDs das mensagens removidas.

Este método evita remoções indesejadas por erro de sincronização entre cliente e servidor, que podem acontecer caso uma mensagem tenha sido marcada como "deleted" por outro cliente.

Assim como expunge, este método não garante a remoção correta para todos os servidores, já que algumas implementações para a remoção não seguem o fluxo padrão.

Parameters:
Name Type Description
uidSet string | number | Array.<number>

Conjunto de UIDs de mensagens a serem removidas. Pode ser um número, uma lista de números ou uma string com expressão suportada pelo protocolo IMAP.
See:
Returns:

Lista de UIDs das mensagens que foram removidas.

Type
Array.<number>

uidFetch(uidSet [, query])

Faz o download de mensagens da caixa de entrada corrente. Equivalente a fetch, mas usando unique IDs.

Parameters:
Name Type Argument Description
uidSet string | number | Array.<number>

Conjunto de UIDs de mensagens a serem baixadas. Pode ser um número, uma lista de números ou uma string com expressão suportada pelo protocolo IMAP.
query string <optional>

Lista indicando quais dados serão baixados. Essa lista é composta por itens separados por espaço e, caso haja mais de um item, encapsulados entre parênteses.

Por padrão, a lista usada pelo método é (FLAGS UID INTERNALDATE RFC822.SIZE RFC822), que traz todos os dados suportados por este cliente e marca a mensagem como lida.
See:
Returns:

Uma lista contendo as mensagens que foram baixadas. Independente da query, as mensagens baixadas sempre conterão messageId e uid.

Type
Array.<ImapEmail>

uidMove(uidSet, destinationMailbox)

Move mensagens de uma caixa de entrada para outra. Equivalente a move, mas usando unique IDs.

Parameters:
Name Type Description
uidSet string | number | Array.<number>

Conjunto de UIDs de mensagens a serem movidas. Pode ser um número, uma lista de números ou uma string com expressão suportada pelo protocolo IMAP.
destinationMailbox string

Caixa de entrada de destino.
See:

uidSearch(query)

Busca mensagens na caixa de entrada corrente. Equivalente a search, mas usando unique IDs.

Parameters:
Name Type Description
query string | SearchOptions

Um comando suportado pelo protocolo IMAP ou um objeto de opções de busca.
See:
Returns:

Uma lista contendo os UIDs das mensagens que correspondem à busca.

Type
Array.<number>

uidStore(uidSet, query)

Altera o conjunto de flags das mensagens especificadas. Equivalente a store, mas usando unique IDs.

Parameters:
Name Type Description
uidSet string | number | Array.<number>

Conjunto de UIDs de mensagens a serem modificadas. Pode ser um número, uma lista de números ou uma string com expressão suportada pelo protocolo IMAP.
query string

Comando suportado pelo protocolo IMAP com as flags a serem modificadas.
See: