Ações de E-mail (Office 365)
Ações para ler, navegar, baixar anexos e enviar e-mails usando a API do Office 365.
Para usar estas ações é necessário ter as credenciais do aplicativo Azure: Tenant ID, Client ID, Client Secret e User ID.
Para seguir um passo a passo de criação do app: Tutorial de Criação do App na Azure
Observação: o parâmetro folder_name por padrão é definido como Caixa de Entrada no cliente.
Importante sobre retornos (variáveis de estado)
- As ações expõem os valores retornados como variáveis de estado que podem ser lidas pelo integrador.
- Para acessar um valor retornado, atribua uma variável local à variável de estado usando o prefixo $. O nome deve ser exatamente igual à chave retornada pela ação.
Exemplo genérico:
# chama a action
office365.create_office365_client("TENANT", "CLIENT", "SECRET", "USER")
# lê o cliente criado e a contagem de e-mails
email_client = $email_client
emails_count = $emails_count
Ações
As ações abaixo estão disponíveis e documentadas com parâmetros, retornos e exemplos de uso.
office365.create_office365_client
Cria uma nova conexão com a API do Office 365 e carrega a lista inicial de e-mails.
Parâmetros:
- tenant_id — Tenant ID do app criado na Azure.
- client_id — Client ID do app na Azure.
- client_secret — Client Secret (segredo) do app.
- user_id — ID do usuário (conta) a ser conectada.
- pagination_limit (opcional) — quantidade de e-mails por página (padrão: 50).
- folder_name (opcional) — nome da pasta inicial (padrão: Caixa de Entrada).
Retorno (variáveis de estado):
- email_client — objeto de conexão que deve ser passado para as demais ações.
- emails_count — número total de e-mails na pasta padrão após o carregamento.
- current_folder — nome da pasta atual (string). No retorno padrão o valor será inbox.
Exemplo:
office365.create_office365_client("TENANT", "CLIENT", "SECRET", "USER")
email_client = $email_client
emails_count = $emails_count
current_folder = $current_folder
office365.get_current_email
Retorna os detalhes do e-mail na posição atual do cliente (o e-mail "ativo").
Parâmetros:
- email_client — objeto retornado por office365.create_office365_client.
Retorno (variáveis de estado):
- id — identificador do e-mail na API Office 365.
- from — nome do remetente.
- from_address — endereço de e-mail do remetente.
- subject — assunto da mensagem.
- date — data/hora de recebimento.
- has_attachments — booleano indicando se há anexos.
- html_body — corpo da mensagem em HTML.
- check_read — booleano indicando se a mensagem foi lida.
Exemplo:
office365.get_current_email($email_client)
email_id = $id
from_name = $from
subject = $subject
has_attachments = $has_attachments
office365.next_email
Move a posição atual para o próximo e-mail (mais recente) e retorna seus detalhes.
Parâmetros:
- email_client — objeto de conexão.
Retorno (variáveis de estado):
- mesmos campos de get_current_email (id, from, from_address, subject, date, has_attachments, html_body, check_read)
Exemplo:
office365.previous_email
Move a posição atual para o e-mail anterior (mais antigo) e retorna seus detalhes.
Parâmetros:
- email_client — objeto de conexão.
Retorno (variáveis de estado):
- mesmos campos de get_current_email
Exemplo:
office365.list_folders
Retorna a lista de pastas disponíveis na conta conectada.
Parâmetros:
- email_client — objeto de conexão.
Retorno (variáveis de estado):
- folders — lista de nomes de pastas disponíveis.
Exemplo:
office365.select_folder
Altera a pasta atual para a pasta especificada e recarrega os e-mails dessa pasta.
Parâmetros:
- email_client — objeto de conexão.
- folder_name — nome da pasta para selecionar.
Retorno (variáveis de estado):
- current_folder — nome da pasta selecionada.
- emails_count — número total de e-mails na pasta selecionada.
Exemplo:
office365.select_folder($email_client, "Rascunhos")
current_folder = $current_folder
emails_count = $emails_count
office365.move_to
Move o e-mail atual para outra pasta existente.
Parâmetros:
- email_client — objeto de conexão.
- to_folder — nome da pasta de destino.
Retorno: - Esta ação não retorna variáveis de estado.
Exemplo:
office365.find_attachments
Retorna os anexos do e-mail atual ou filtra por nome parcial.
Parâmetros:
- email_client — objeto de conexão.
- attach_name (opcional) — nome ou parte do nome do anexo para filtrar.
Retorno (variáveis de estado):
- attachments — lista com metadados dos anexos encontrados (cada item contém name, contentBytes, etc.).
- attachments_count — número de anexos encontrados.
Exemplo:
office365.find_attachments($email_client, "relatorio")
attachments = $attachments
attachments_count = $attachments_count
Observações:
- attachments contém o conteúdo em base64 no campo contentBytes quando for necessário salvar o arquivo.
office365.save_attachment
Salva anexos do e-mail atual para uma pasta local. Evita sobrescrever arquivos existentes renomeando duplicados com sufixo -1, -2, etc.
Parâmetros:
- email_client — objeto de conexão.
- file_path — pasta local onde os arquivos serão salvos.
- attach_name (opcional) — nome parcial para filtrar anexos.
- mime_type (opcional) — (não utilizado atualmente, reservado).
- only_attachments (opcional) — (não utilizado atualmente, reservado).
Retorno (variáveis de estado):
- saved_files — lista com os caminhos completos dos arquivos salvos.
Exemplo:
office365.save_attachment($email_client, "C:/temp", attach_name="fatura")
saved_files = $saved_files
Exceções:
- FileNotFoundException — lançada quando nenhum anexo for encontrado para salvar.
office365.send_email
Envia um e-mail usando a conta conectada.
Parâmetros:
- email_client — objeto de conexão.
- to — lista ou string com destinatários para o campo TO.
- subject — assunto da mensagem.
- text (opcional) — corpo em texto simples.
- html (opcional) — corpo em HTML.
- attachments (opcional) — lista de caminhos para arquivos a anexar.
- to_cc (opcional) — lista de destinatários em CC.
- to_bcc (opcional) — lista de destinatários em BCC.
Retorno (variáveis de estado):
- email_sent — booleano indicando sucesso do envio.
- status_code — código de status retornado pela API.
- message_status — mensagem com detalhes do resultado do envio.
Exemplo:
office365.send_email($email_client, ["[email protected]"], "Assunto", text="texto")
email_sent = $email_sent
status_code = $status_code
message_status = $message_status