Microsoft 365: conectar caixas de e-mail

Para ler os e-mails no Microsoft 365 e criar rascunhos neles, o assistente precisa de acesso pelo Microsoft Graph. Há dois caminhos, e os dois se apoiam em um aplicativo que a organização registra no próprio Microsoft Entra ID. O draften não tem um aplicativo comum ao qual você só daria consentimento. Isso vale tanto para o nosso serviço quanto para a instalação no seu próprio servidor.

Qual caminho escolher

Para uma organização com várias caixas de e-mail, o caminho para toda a organização é mais simples: o administrador o configura uma vez e os proprietários das caixas não fazem nada. Com a conta da caixa de e-mail convém quando você não quer dar ao aplicativo acesso a todas as caixas do diretório, ou quando vai adotar de qualquer forma a entrada com conta Microsoft.

Você pode usar os dois caminhos ao mesmo tempo; cada caixa de e-mail usa um deles.

Nunca dê ao aplicativo a permissão Mail.Send. O draften não envia nada e, sem essa permissão, nem consegue – e é exatamente essa a ideia.

Caminho A: para toda a organização

Você precisa de uma conta com o perfil administrador global ou administrador de funções com privilégios – só eles dão consentimento para permissões de aplicativo do Microsoft Graph. O registro em si também pode ser criado por um administrador de aplicativos.

No Microsoft Entra

1. Abra https://entra.microsoft.com → Identity → Applications → App registrations → New registration.
2. Preencha um nome, por exemplo draften – e-mails, escolha Accounts in this organizational directory only, deixe a Redirect URI vazia e clique em Register.
3. Na página Overview, anote o Application (client) ID e o Directory (tenant) ID.
4. Certificates & secrets → Client secrets → New client secret: uma descrição (por exemplo draften) e a validade, no máximo 24 meses. Depois de salvar, copie na hora a coluna Value – ela só aparece agora. O Secret ID o draften não precisa. Anote também a data de validade.
5. API permissions → Add a permission → Microsoft Graph → Application permissions. Marque Mail.ReadWrite e MailboxSettings.ReadWrite e clique em Add permissions. MailboxSettings.ReadWrite serve só para a cor da categoria no Outlook; sem ela, a categoria é adicionada sem cor. Se quiser, adicione User.Read.All – com ela o draften verifica os aliases da caixa de e-mail; sem ela, o teste de conexão avisa, nos aliases, que não consegue verificá-los.
6. Clique em Grant admin consent for … e confirme. Todas as linhas precisam ter a marca verde.

No draften

1. Abra Organização → Integrações, o cartão Acesso aos e-mails de toda a organização. Os registros são gerenciados pelo proprietário ou por um administrador da organização.
2. Sistema: Microsoft 365 (Entra). Preencha Nome, Directory (tenant) ID, Application (client) ID, Client secret (o valor do passo 4, não o ID dele) e O segredo expira. Clique em Adicionar registro. O segredo é guardado criptografado e nunca mais é exibido.
3. Um registro sozinho não conecta nada. Na página de cada caixa de e-mail, no cartão Acesso aos e-mails, escolha este registro em Usar, clique em Aplicar e depois em Testar a conexão. A escolha só aparece para quem é ao mesmo tempo proprietário da caixa de e-mail e proprietário ou administrador da organização (o proprietário da organização é proprietário de todas as caixas). O procedimento completo, com capturas de tela, está no guia Adicionar e conectar uma caixa de e-mail.

Com a caixa de e-mail automática ativada (Como os membros entram), uma nova caixa de e-mail é vinculada sozinha ao registro quando há exatamente um ativo para o Microsoft 365.

Restringir a caixas de e-mail escolhidas (opcional)

A permissão de aplicativo alcança todas as caixas de e-mail do diretório; quem faz a guarda é o draften (um membro não consegue adicionar uma caixa de e-mail; o assistente não envia nem apaga nada). Quem quiser também uma barreira técnica restringe o aplicativo a um grupo de segurança com a política ApplicationAccessPolicy no Exchange Online (PowerShell com o módulo ExchangeOnlineManagement):

Connect-ExchangeOnline -UserPrincipalName admin@<tenant>.onmicrosoft.com
New-DistributionGroup -Name "draften - caixas permitidas" -Alias draften-caixas -Type Security -Members caixa@firma.cz
New-ApplicationAccessPolicy -AppId <Application (client) ID> -PolicyScopeGroupId draften-caixas@firma.cz -AccessRight RestrictAccess -Description "draften: só caixas permitidas"
Test-ApplicationAccessPolicy -Identity caixa@firma.cz -AppId <Application (client) ID>

Cada caixa de e-mail adicional precisa então entrar também no grupo; senão, o teste de conexão falha com o erro 403 (AppOnly AccessPolicy). A política costuma entrar em vigor em até uma hora; já vimos levar quatro horas. Como alternativa mais nova, a Microsoft oferece o RBAC for Applications no Exchange Online; esse ainda não descrevemos aqui.

Troca do segredo

O segredo tem validade limitada, e o draften não manda nenhum aviso sobre o fim dela – a data no cartão fica amarela 30 dias antes de expirar e, depois, vermelha. Coloque um lembrete na sua agenda. Antes que ele expire:

1. No Entra, crie um novo client secret no registro (passo 4 acima).
2. No draften, escolha Novo segredo no registro e informe o novo valor e a nova data.
3. Apague o segredo antigo no Entra.

Se o segredo expirar antes, as caixas de e-mail se desconectam (invalid_client) e os assistentes as pulam. Depois de trocar o segredo, execute Testar a conexão nas caixas de e-mail – um teste bem-sucedido reativa a caixa.

Caminho B: com a conta da caixa de e-mail (Conectar o Outlook)

Este registro tem permissões delegadas: o aplicativo só pode fazer o que a pessoa conectada pode, e só na caixa de e-mail dela. O mesmo registro serve também para entrar no draften com a conta Microsoft. Mantenha-o separado do registro do caminho A.

No Microsoft Entra

1. No draften, abra primeiro Organização → Como os membros entram, o cartão Entrada com conta e conexão de caixas de e-mail. Ele mostra duas redirect URIs exatamente para o endereço do seu draften – terminam em /auth/callback e /mailboxes/connect/callback. Copie-as de lá; elas precisam coincidir caractere por caractere.
2. Em https://entra.microsoft.com → App registrations → New registration: um nome, por exemplo draften – login, Accounts in this organizational directory only, Redirect URI: plataforma Web e o primeiro endereço do cartão. Clique em Register.
3. Authentication → na plataforma Web, Add URI → o segundo endereço do cartão → Save.
4. Em Overview, anote o Application (client) ID e o Directory (tenant) ID.
5. Certificates & secrets → New client secret → copie o Value e anote a data de validade.
6. API permissions → Add a permission → Microsoft Graph → Delegated permissions: openid, profile, email, offline_access, User.Read, Mail.ReadWrite e MailboxSettings.ReadWrite. Sem offline_access a conexão não se mantém – o draften não receberia um token de atualização.
7. Clique em Grant admin consent for …. Se a sua organização proíbe que os usuários consintam com aplicativos, sem este passo a conexão terminaria com a mensagem de que o consentimento foi recusado.

No draften

1. O proprietário da organização, no cartão Entrada com conta e conexão de caixas de e-mail, preenche em Registro no Entra para “Entrar com a Microsoft” e “Conectar o Outlook” os valores Application (client) ID e Client secret e clica em Salvar.
2. O proprietário da caixa de e-mail abre a página da caixa e, no cartão Acesso aos e-mails, clica em Conectar o Outlook. Ele entra com a conta dessa caixa de e-mail – o draften recusa outra conta – e permite o acesso. Só o proprietário da caixa vê o botão, e só quando a organização tem o registro.
3. Depois, Testar a conexão.

A entrada com conta Microsoft você ativa na mesma página: em ID do diretório Microsoft (Entra), coloque o Directory (tenant) ID. Assim que a organização tiver o registro e o ID do diretório, os membros entram com a conta Microsoft e as senhas deles deixam de funcionar – veja Como os membros entram.

Quando a caixa de e-mail se desconecta

• O segredo do registro expirou – crie um novo no Entra, salve-o no cartão Entrada com conta e conexão de caixas de e-mail e clique em Reconectar o Outlook nas caixas de e-mail.
• A pessoa saiu ou a conta dela foi bloqueada – a Microsoft deixa de emitir tokens e o draften desconecta a caixa de e-mail. Uma caixa sem login próprio você conecta pelo caminho A.
• “O provedor não emitiu um token de atualização” – falta ao registro a permissão offline_access (passo 6).
• “Entrou uma conta diferente do endereço da caixa de e-mail” – ao conectar, entre com a conta exatamente dessa caixa de e-mail; quem tem várias contas Microsoft no navegador escolhe a certa.

Erros do teste de conexão

O teste verifica três etapas: Acesso, Token e permissão e Leitura da Caixa de Entrada. Cada uma recebe uma marca de confirmação ou um X com o motivo:

Outros erros estão em Solução de problemas.