Pular para conteúdo

Ações de E-mail

Ações de e-mail são usadas para interagir com servidores de e-mail enviando e recebendo mensagens.

Para enviar e-mails é necessário ter uma credencial SMTP para o Mail Server, e para receber e-mails é necessário ter uma credencial IMAP ou POP3 para o Mail Server.

Importante: recomendamos o uso de conexões IMAP para recebimento de e-mails, pois este é um protocolo muito mais recente e oferece mais funcionalidades e melhor controle.

Ações

email.close

Fecha a conexão ativa com o Mail Server.

Parâmetros:

email_client - conexão do cliente com o Mail Server. As conexões são criadas usando email.create_imap_client ou email.create_pop_client

quit (opcional) - ao usar o cliente POP3, para persistir todos os e-mails lidos e exclusões, o parâmetro quit deve ser definido como True.

Retorna:

Esta ação não dá retorno.

Exceções:

Esta ação não oferece exceções.

email.create_imap_client

Crie uma nova conexão com o Mail Server, usando o protocolo IMAP.

Parâmetros:

user - usuário para autenticar com o Mail Server

password - senha para autenticar com o Mail Server

host - IP ou nome para conectar com o Mail Server

port (opcional) - porta no Mail Server usada para conexão IMAP (padrão=995).

default_folder (opcional) - nome da caixa de correio para iniciar a leitura (deafult='inbox').

Retorna:

email_client - email_client para ser usado em outras ações de e-mail.

emails_count - retorna o número total de e-mails em default_folder.

current_folder - nome da pasta atual.

Exceções:

Esta ação não oferece exceções.

email.create_pop_client

Crie uma nova conexão com o Mail Server, usando o protocolo POP3.

Parâmetros:

user - usuário para autenticar com o Mail Server

password - senha para autenticar com o Mail Server

host - IP ou nome para conectar com o Mail Server

port (opcional) - porta no Mail Server usada para conexão IMAP (padrão=995).

Retorna:

email_client - email_client para ser usado em outras ações de e-mail.

email_count - retorna o número total de e-mails em default_folder.

Exceções:

Esta ação não oferece exceções.

email.delete

Exclui a mensagem atual.

Parâmetros:

email_client - conexão do cliente com o Mail Server. As conexões são criadas usando email.create_imap_client ou email.create_pop_client

Retorna:

Esta ação não dá retorno.

Exceções:

Esta ação não oferece exceções.

email.find_attachments

Permite retornar todos os anexos do e-mail atual ou pesquisar um anexo específico por nome e/ou tipo MIME.

Parâmetros:

email_client - conexão do cliente com o Mail Server. As conexões são criadas usando email.create_imap_client ou email.create_pop_client

attach_name (opcional) - nome ou nome parcial do anexo a ser procurado (padrão=não filtrar por nome)

mime_type (opcional) - tipo mime para filtrar anexos (padrão=não filtrar por tipo mime)

only_attachments (opcional) - Definido como True incluirá arquivos definidos como anexos. Definido como False incluirá todos os arquivos, anexos e embutidos (padrão=True)

Retorna:

attachments - lista com todos os anexos que satisfazem a pesquisa.

attachments_count - número de anexos que satisfazem a pesquisa.

Exceções:

Esta ação não oferece exceções.

email.get_current_email

Retorna a mensagem de e-mail na posição atual no cliente de e-mail.

Parâmetros:

email_client - conexão do cliente com o Mail Server. As conexões são criadas usando email.create_imap_client ou email.create_pop_client

Retorna:

from - texto com nome (se definido) e endereço de e-mail do remetente da mensagem.

from_address - retorna apenas o endereço de e-mail do remetente da mensagem.

to - texto com nome (se definido) e endereço de e-mail dos destinatários.

subject - assunto da mensagem de e-mail.

date - dados e hora em que a mensagem foi enviada.

body - conteúdo da mensagem de e-mail como texto simples.

html_body - conteúdo da mensagem de e-mail como conteúdo HTML.

attachments_count - número de anexos na mensagem.

has_attachments - configuração de variável booleana se a mensagem de e-mail tem anexos ou não.

Exceções:

Esta ação não oferece exceções.

email.list_folders

Retorna uma lista de todas as pastas disponíveis na conta de e-mail conectada.

Parâmetros:

email_client - conexão do cliente com o Mail Server. As conexões são criadas usando email.create_imap_client ou email.create_pop_client

Retorna:

folders - lista com o nome de todas as pastas da conta de e-mail conectada.

Exceções:

Esta ação não oferece exceções.

email.move_to

Mova o e-mail atual para outra pasta existente da conta de e-mail.

Esta ação está disponível apenas para clientes IMAP.

Parâmetros:

email_client - conexão do cliente com o Mail Server. As conexões são criadas usando email.create_imap_client ou email.create_pop_client

to_folder - nome da pasta para onde a mensagem atual deve ser movida.

Ações de E-mail

Ações de e-mail permitem enviar e receber mensagens usando credenciais SMTP/IMAP/POP3.

Observação: apenas métodos anotados com @decorators.robotaction estão documentados aqui. Os retornos das ações viram variáveis de estado — por exemplo, se a ação retorna {'emails_count': 10} você acessa com $emails_count.

Para envio use SMTP; para recebimento recomendamos IMAP (mais recursos). Algumas ações só funcionam com IMAP — isso está indicado onde aplicável.

Métodos expostos

email.send_email

Envia uma mensagem usando SMTP.

Parâmetros: - sender — e-mail do remetente (FROM). - to — destinatários (string com ; ou lista). - subject — assunto da mensagem. - smtp_user — usuário SMTP. - smtp_password — senha SMTP. - smtp_server — host do servidor SMTP. - smtp_port (opcional, default 25) — porta do servidor. - tls (opcional, default False) — usar STARTTLS em vez de SSL. - text (opcional) — corpo em texto simples. - html (opcional) — corpo em HTML. - attach_path (opcional) — caminho ou lista de caminhos para anexos (assets). - signature_img (opcional) — imagem de assinatura (asset) embutida no HTML. - no_auth (opcional) — se True, não faz login no servidor SMTP. - to_cc / to_bcc (opcionais) — CC e BCC (string ou lista).

Retorno: nenhum (ação retorna vazio).

Exceções: - AuthorizationException — falha na autenticação SMTP. - MarvinRuntimeException — erros de comunicação com o servidor.

email.create_imap_client

Cria e conecta um cliente IMAP para leitura/gerenciamento de e-mails.

Parâmetros: - user, password, host. - port (opcional, default 995). - default_folder (opcional, default 'inbox') — pasta inicial.

Retorno (variáveis de estado): - email_client — objeto de conexão (usar nas demais ações). - emails_count — número total de e-mails na pasta inicial. - current_folder — nome da pasta atual (geralmente default_folder).

email.create_pop_client

Cria e conecta um cliente POP3.

Parâmetros: - user, password, host. - port (opcional, default 995).

Retorno: - email_client — objeto de conexão. - emails_count — número total de e-mails.

email.get_current_email

Retorna os campos do e-mail na posição atual do cliente.

Parâmetros: - email_client — objeto retornado por create_imap_client/create_pop_client.

Retorno (variáveis de estado): - from — remetente (nome + endereço quando disponível). - from_address — somente endereço de e-mail do remetente. - to — destinatários. - subject — assunto. - date — data/hora do envio. - body — conteúdo em texto plano. - html_body — conteúdo em HTML. - attachments_count — número de anexos. - has_attachments — booleano indicando existência de anexos.

email.next_email / email.previous_email

Navega para o próximo/anterior e retorna os mesmos campos de get_current_email.

Parâmetros: - email_client.

Retorno: - mesmo conjunto de chaves que get_current_email.

email.update_mailbox

Atualiza contagem e estado da mailbox (recarrega informações).

Parâmetros: - email_client.

Retorno: - emails_count — número total de e-mails na pasta atual.

email.delete

Deleta a mensagem atual (comportamento pode variar entre POP/IMAP).

Parâmetros: - email_client.

Retorno: - emails_count — novo total de e-mails na pasta.

email.close

Fecha a conexão ativa.

Parâmetros: - email_client. - quit (opcional) — para POP3 pode ser necessário usar quit=True para persistir alterações.

Retorno: nenhum.

email.list_folders

Lista as pastas disponíveis (IMAP).

Parâmetros: - email_client.

Retorno: - folders — lista de nomes de pastas.

email.select_folder

Altera a pasta atual (IMAP only).

Parâmetros: - email_client, folder — nome da pasta.

Retorno: - current_folder — nome da nova pasta. - emails_count — número de e-mails na nova pasta.

email.search

Executa uma busca IMAP com filtro (IMAP only).

Parâmetros: - email_client, search_filter — filtro conforme RFC3501.

Retorno: - emails_count — total de e-mails resultantes/na pasta.

email.move_to

Mova a mensagem atual para outra pasta (IMAP only).

Parâmetros: - email_client, to_folder — destino.

Retorno: - emails_count — contagem atualizada.

email.store

Comando genérico IMAP STORE para flags/atributos específicos (IMAP only).

Parâmetros: - email_client, message, value.

Retorno: nenhum.

email.find_attachments

Procura anexos no e-mail atual, filtrando por nome e/ou mime type.

Parâmetros: - email_client, attach_name (opcional), mime_type (opcional), only_attachments (opcional, default True).

Retorno: - attachments — lista de objetos de anexo. - attachments_count — número de itens retornados.

email.save_attachment

Salva anexos do e-mail atual no file_path fornecido.

Parâmetros: - email_client, file_path, attach_name (opcional), mime_type (opcional), only_attachments (opcional, default True).

Retorno: - saved_files — lista de caminhos completos dos arquivos salvos.

Exceções: - FileNotFoundException quando nenhum anexo é encontrado para os filtros.

Se desejar, adiciono exemplos curtos de uso (ex.: como ler $saved_files ou $attachments_count) ou corrijo pequenos problemas pontuais no código email.py. Atualize as informações de contagem de e-mails e lista de e-mails dentro da pasta atual.