Ligar caixas de correio

Como funciona a ligação de uma caixa de correio

O Campbooks lê e envia o Gmail e o Zoho Mail através da API do próprio fornecedor. Qualquer outra caixa de correio (Yahoo, AOL, iCloud, Fastmail, GMX, WEB.DE, Yandex, um domínio próprio) liga-se por IMAP e SMTP com uma palavra-passe de aplicação: veja Caixas de correio IMAP. O Outlook e o Microsoft 365 estão para chegar.

No Gmail e no Zoho não há nada extra para registar. O cliente OAuth que configurou para o Início de sessão é o mesmo cliente que liga a caixa de correio. Usa o mesmo URI de redirecionamento e o mesmo ID de cliente e ficheiro de segredo. Um fornecedor oferece a ligação de correio assim que o seu cliente está configurado, e não antes.

• Adicionar uma caixa de correio. Na aplicação, abra Definições, depois Caixas de correio, e escolha Adicionar uma caixa de correio. Pede primeiro o endereço. Um endereço Gmail ou Zoho segue para o ecrã de consentimento do fornecedor, que pede acesso ao correio; qualquer outro endereço recebe o passo da palavra-passe de aplicação. O Gmail e o Zoho só são oferecidos depois de a sua instância configurar o respetivo cliente. Passos para os membros: Ligar a sua caixa de correio.
• Usar também para iniciar sessão. O passo de ligar tem uma caixa, «Usar também esta conta para iniciar sessão», assinalada por omissão. Desassinale-a para uma caixa partilhada, como support@. Fica ligada, mas nunca passa a ser uma forma de iniciar sessão.
• Quem a vê. Uma ligação pertence ao espaço de trabalho e regista quem a ligou. Os proprietários e administradores veem todas as caixas de correio do espaço de trabalho.
• Credenciais. A autorização que o Campbooks recebe do fornecedor, ou a palavra-passe de uma caixa de correio IMAP, é selada com a chave secreta da instância. Se perder a chave, as ligações deixam de poder ser abertas e cada pessoa tem de ligar de novo. Veja A chave secreta da instância.
• Desligar. Desligar pára a sincronização e revoga a autorização no fornecedor. Escolhe se o correio que já está no Campbooks é apagado (por omissão) ou mantido como histórico só de leitura. O correio no Gmail ou no Zoho nunca é tocado. Sair do espaço de trabalho, ou apagá-lo, também revoga as autorizações.
• Estado. Cada caixa de correio mostra um de quatro estados: A sincronizar, O membro tem de voltar a ligar, Abrandado pelo fornecedor ou Com falhas. Uma caixa que tem de ser ligada de novo tem um botão Voltar a ligar para quem a ligou.

Ligar correio exige o início de sessão incluído. Se definir CAMPBOOKS_AUTH__ISSUER para um emissor externo, a ligação de caixas de correio fica desativada.

Gmail

Funciona com Gmail pessoal e com contas Google Workspace.

O que o Campbooks pede à Google

O Campbooks pede openid, email e profile para identificar a conta, e um âmbito do Gmail:

https://www.googleapis.com/auth/gmail.modify

Esse âmbito lê o correio, altera etiquetas e envia. Não pode apagar correio de forma permanente.

Configurar o projeto Google Cloud

1. Na consola Google Cloud, crie um projeto ou escolha o que usa para o início de sessão.

2. Abra APIs & Services, depois Library, e ative a Gmail API nesse projeto. Sem ela, a Google recusa todos os pedidos de correio.

3. Abra OAuth consent screen (nas consolas mais recentes, Google Auth Platform). Escolha o tipo de utilizador:

   • External para contas Gmail pessoais, ou para utilizadores do Workspace fora da sua organização.
   • Internal se todos os que vão ligar estiverem na sua própria organização Google Workspace. Uma aplicação interna não precisa de verificação.

4. Adicione os âmbitos openid, email, profile e https://www.googleapis.com/auth/gmail.modify.

5. Defina o estado de publicação. Veja a secção seguinte.

6. Abra Credentials, depois Create credentials, depois OAuth client ID. Escolha Web application e adicione este URI de redirecionamento autorizado:

   https://campbooks.example.com/auth/callback/google

   Use o seu próprio CAMPBOOKS_PUBLIC_URL. O URI tem de coincidir exatamente, sem barra final.

7. Ponha o ID de cliente no .env e o segredo do cliente em deploy/secrets/google-client-secret, e execute docker compose up -d. As permissões do ficheiro e as linhas do .env são as de Iniciar sessão com Google, Microsoft ou Zoho:

   CAMPBOOKS_GOOGLE__CLIENT_ID=your-client-id
   CAMPBOOKS_GOOGLE__CLIENT_SECRET_FILE=/run/secrets/campbooks/google-client-secret

Testing, publicação e verificação

A Google trata o gmail.modify como um âmbito restrito. Isto decide quem pode ligar:

• Testing. Só podem ligar os utilizadores de teste que indicar, até 100. Os refresh tokens duram 7 dias, por isso todas as ligações param ao fim de uma semana e precisam de ser refeitas. Use o Testing apenas para experimentar.
• Em produção, não verificada. Qualquer pessoa pode ligar, mas vê o ecrã «A Google não verificou esta aplicação» e tem de escolher Avançadas e continuar. Os refresh tokens não expiram ao fim de 7 dias. Numa instância pessoal com poucos utilizadores, isto costuma ser aceitável. A Google também limita as aplicações não verificadas a 100 utilizadores no total.
• Em produção, verificada. A Google retira o aviso depois de rever a aplicação. Para um âmbito restrito, a Google exige uma avaliação de segurança. Raramente compensa numa instância auto-alojada.

Para uma configuração duradoura, publique a aplicação (Publish app no ecrã de consentimento) e aceite o aviso.

Como sincroniza

O Campbooks consulta o Gmail periodicamente. Não há configuração de push nem nada a registar na Google para isso. Depois de uma sincronização que encontrou alterações, a seguinte corre no prazo de um minuto. Quando nada muda, o intervalo aumenta, até quatro horas. Uma ligação nova lê, por omissão, os últimos 90 dias. Pode alterar isto no Ajuste fino.

Zoho Mail

O que o Campbooks pede ao Zoho

O Campbooks pede openid, email e profile, e quatro âmbitos do Zoho Mail:

Âmbito	Para quê
ZohoMail.accounts.READ	Listar as contas de correio do início de sessão.
ZohoMail.folders.READ	Ler as pastas.
ZohoMail.messages.ALL	Ler, alterar e enviar mensagens.
ZohoMail.tags.ALL	Ler e criar etiquetas, para os fluxos.

O ecrã de consentimento do Zoho é tudo ou nada. Se faltar algum âmbito na autorização, o Campbooks recusa-a e pede para ligar de novo.

Configurar a aplicação Zoho

1. Abra a consola da API do Zoho da sua região, por exemplo https://api-console.zoho.eu para a Europa. Adicione um cliente do tipo Server-based Applications.

2. Ative o Multi-DC, para que um só cliente funcione em todos os centros de dados do Zoho. Sem ele, o cliente só funciona no centro de dados onde o criou.

3. Adicione o URI de redirecionamento:

   https://campbooks.example.com/auth/callback/zoho

4. Uma aplicação Zoho do tipo servidor recebe os âmbitos em cada pedido, por isso não há mais nada a registar para eles.

5. Ponha o ID de cliente no .env e o segredo do cliente em deploy/secrets/zoho-client-secret, e execute docker compose up -d:

   CAMPBOOKS_ZOHO__CLIENT_ID=your-client-id
   CAMPBOOKS_ZOHO__CLIENT_SECRET_FILE=/run/secrets/campbooks/zoho-client-secret

Centros de dados

O Zoho guarda cada conta num centro de dados, e o Campbooks lê o correio a partir daí. Estes servidores de contas são aceites:

Região	Servidor de contas
Estados Unidos	https://accounts.zoho.com (por omissão)
Europa	https://accounts.zoho.eu
Índia	https://accounts.zoho.in
Austrália	https://accounts.zoho.com.au
Japão	https://accounts.zoho.jp
Canadá	https://accounts.zoho.ca
Arábia Saudita	https://accounts.zoho.sa
Reino Unido	https://accounts.zoho.uk

Com o Multi-DC ativo, deixe CAMPBOOKS_ZOHO__ACCOUNTS_SERVER por definir. Sem Multi-DC, defina-o com o servidor de contas do centro de dados onde registou o cliente:

CAMPBOOKS_ZOHO__ACCOUNTS_SERVER=https://accounts.zoho.eu

Várias contas de correio num só início de sessão

Um início de sessão do Zoho pode ter várias contas de correio. Cada conta de correio passa a ser a sua própria caixa de entrada no Campbooks. Uma pessoa pode ligar mais do que um início de sessão do Zoho.

Quando alguém se regista com o Zoho, o Zoho pede uma segunda vez acesso ao correio, e só se a conta for nova. Iniciar sessão de novo nunca pede.

Voltar a ligar uma vez, para as etiquetas

As ligações do Zoho feitas antes de o âmbito das etiquetas ser acrescentado continuam a sincronizar, mas sem etiquetas nem fluxos. Para os ter, volte a ligar a caixa de correio uma vez em Definições, depois Caixas de correio. O Campbooks passa então a acrescentar etiquetas Campbooks/<Fluxo> no Zoho para os fluxos para os quais o Zoho não tem lugar próprio.

Como sincroniza

O Campbooks consulta o Zoho periodicamente, porque o Zoho não tem push. O Zoho também não tem registo de alterações, por isso o Campbooks relê ainda toda a janela de cada caixa de correio a cada 6 horas, por omissão. Respeita 60 pedidos por minuto por cada início de sessão do Zoho. Altere isto no Ajuste fino.

Ajuste fino

Tudo isto é opcional, e os valores por omissão servem à maioria das instâncias. Acrescente-os ao .env e execute docker compose up -d. Também estão listados em Configuração.

Variável	Valor por omissão	O que faz
CAMPBOOKS_CONNECTORS__GMAIL__BACKFILL_DAYS	90	Até onde lê uma ligação Gmail nova. De 1 a 3650.
CAMPBOOKS_CONNECTORS__POLL__MIN_SECONDS	60	Intervalo após uma sincronização que encontrou alterações.
CAMPBOOKS_CONNECTORS__POLL__MAX_SECONDS	14400	Intervalo mais longo de uma caixa de correio parada.
CAMPBOOKS_CONNECTORS__ZOHO__BACKFILL_DAYS	90	Até onde lê uma caixa Zoho nova. De 1 a 3650.
CAMPBOOKS_CONNECTORS__ZOHO__REQUESTS_PER_MINUTE	60	Pedidos que cada início de sessão do Zoho pode fazer por minuto.
CAMPBOOKS_CONNECTORS__ZOHO__SWEEP_MINUTES	360	Minutos entre releituras completas da janela de uma caixa Zoho.

Os limites de tamanho, o orçamento de quota da Google e os limiares de falha estão em Configuração.

Resolução de problemas

O que vê	Causa e correção
Google: Error 400: redirect_uri_mismatch	O URI de redirecionamento no cliente Google não é exatamente ${CAMPBOOKS_PUBLIC_URL}/auth/callback/google. Verifique o https://, o anfitrião e que não há barra final.
Google: access_denied, ou «This app is blocked» ou «has not completed the Google verification process»	A aplicação está em Testing e a pessoa não é um utilizador de teste. Adicione-a aos utilizadores de teste do ecrã de consentimento, ou publique a aplicação.
Google: a sincronização falha com 403 accessNotConfigured, ou «Gmail API has not been used in project»	A Gmail API não está ativa no projeto a que o cliente pertence. Ative-a em APIs & Services, depois Library, e aguarde alguns minutos.
Google: as ligações páram ao fim de cerca de 7 dias	A aplicação está em Testing, que limita os refresh tokens a 7 dias. Publique a aplicação e volte a ligar cada caixa de correio.
Zoho: invalid_client	O cliente foi registado noutro centro de dados. Ative o Multi-DC, ou defina CAMPBOOKS_ZOHO__ACCOUNTS_SERVER com o servidor de contas do centro de dados onde criou o cliente.
Zoho: um erro de redirecionamento no ecrã de consentimento	O URI de redirecionamento no cliente Zoho não é exatamente ${CAMPBOOKS_PUBLIC_URL}/auth/callback/zoho.
«O Campbooks não recebeu acesso ao que escolheu»	A pessoa deixou de fora uma permissão no ecrã de consentimento. Ligue de novo e permita tudo.
«O membro tem de voltar a ligar» numa caixa de correio	O fornecedor revogou ou expirou a autorização. Quem a ligou escolhe Voltar a ligar (ou prime R) em Definições, depois Caixas de correio.
«O Campbooks não reconhece o centro de dados Zoho desta conta»	A conta está num centro de dados fora da lista acima.
O fornecedor não é oferecido em Ligar	O ID de cliente ou o segredo não estão definidos, ou o servidor não foi reiniciado. Verifique docker compose logs server.

Outras caixas de correio

Qualquer outra caixa de correio liga-se por IMAP e SMTP com uma palavra-passe de aplicação. Vem ativado por omissão e só precisa da chave secreta da instância. Veja Caixas de correio IMAP. O correio do Outlook ou Microsoft 365 está para chegar.