Guia da API de E-mail para Desenvolvedores: Sincronização, OAuth e Código (2026)

Integração de API de E-mail: Do OAuth à Sincronização em Tempo Real

Uma integração de API de e-mail real segue quatro fases, independentemente do provedor que você escolher. Leia esta seção como um checklist antes de iniciar sua implementação: pular qualquer etapa aqui é o motivo mais comum para integrações funcionarem em desenvolvimento e falharem em produção.

Autenticação OAuth 2.0

Tanto o Gmail quanto o Microsoft Graph usam o padrão Fluxo de código de autorização OAuth 2.0. Os mecanismos são idênticos: redirecione o usuário para o provedor, receba um código de uso único em sua URL de retorno de chamada, troque-o por um token de atualização de longa duração no lado do servidor e, em seguida, use esse token de atualização para gerar tokens de acesso de curta duração para todas as chamadas de API subsequentes.

• Redirecione o usuário para o endpoint de autorização do provedor com o seu id_cliente, redirect_uri, e o solicitado escopo.
• O usuário concede permissões, o provedor redireciona para a sua URL de callback com um código único código parâmetro.
• Seu servidor troca isso código para um token_de_acesso (vida útil de 1 hora) e um token_de_atualização via um POST de canal secundário.
• Armazenar o token_de_atualização seguramente no lado do servidor, criptografado em repouso. Esta é a credencial de longa duração que você usa para gerar novas tokens de acesso automaticamente.

Nota específica do Gmail: O Gmail não suporta autenticação simples de chave de API para acesso à caixa de correio - o OAuth 2.0 é necessário. Para uma comparação detalhada, consulte Você pode usar uma chave de API com o Gmail?

Enviar e Receber E-mails

Uma vez autenticado, as duas próximas operações cobrem 80% do uso típico da API de E-mail: buscando a caixa de entrada e enviando uma mensagem. Com a API unificada da Unipile, ambos funcionam de forma idêntica no Gmail, Outlook e IMAP através de um único conjunto de endpoints.

# Buscar os últimos 50 e-mails de uma caixa de entrada conectada
curl --request GET \
  --url 'https://api.unipile.com/api/v1/emails?limit=50&folder=inbox' \
  --header 'X-API-KEY: SUA_API_KEY'

# Enviar um e-mail em texto simples
curl --request POST \
  --url 'https://api.unipile.com/api/v1/emails' \
  --header 'X-API-KEY: SUA_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "account_id": "SEU_ACCOUNT_ID",
    "subject": "Olá do Unipile",
    "body": "Olá, este é um e-mail em texto simples",
    "to": [{"display_name":"John Doe","identifier":"john@example.com"}]
  }'

O Unipile também oferece suporte aos recursos avançados de envio típicos que os desenvolvedores esperam: anexos (multipart form-data com múltiplos arquivos), cabeçalhos personalizados passando arrays de X- cabeçalhos prefixados), responder-em-thread usando a mensagem original provider_id), substituição de nome de exibição, aliases de remetente permitidos e rastreamento de abertura / link com eventos de webhook em tempo real. Cada um deles mapeia para um único campo no corpo da solicitação, sem necessidade de negociação de protocolo.

# Enviar com anexos + cabeçalhos personalizados + rastreamento
curl --request POST \
  --url 'https://api.unipile.com/api/v1/emails' \
  --header 'X-API-KEY: SUA_CHAVE_API' \
  --form 'account_id=SEU_ID_DA_CONTA' \
  --form 'subject=Rascunho do contrato' \
  --form 'body=Por favor, encontre o v3 em anexo.' \
  --form 'to=[{"identifier":"sarah@acme.com"}]' \
  --form 'attachments=@/caminho/para/contrato.pdf' \
  --form 'attachments=@/caminho/para/apendice.png' \
  --form 'custom_headers=[{"name":"X-Campaign-ID","value":"q1-outreach"}]' \
  --form 'tracking_options={"opens":true,"links":true,"label":"q1-outreach"}'

Para uma referência completa do desenvolvedor cobrindo todas as opções de envio e comportamento específico do provedor, consulte nossa guia da API de envio de e-mail.

Sincronização de e-mail em tempo real

A sincronização da caixa de entrada é a parte mais complexa de qualquer integração de e-mail e a mais frequentemente incompreendida. Um robusto Sincronização de e-mail A implementação tem três fases distintas: sincronização inicial, sincronização incremental e notificações de webhook em tempo real. Ignorar qualquer um deles resulta em uma integração que funciona no primeiro dia e quebra em escala.

Planeje as renovações desde o primeiro dia: assinaturas de observação do Gmail Pub/Sub expiram após 7 dias e precisam ser renovadas. Assinaturas do Microsoft Graph em recursos de e-mail expiram após um máximo de cerca de 3 dias. Integre a renovação de assinaturas na sua infraestrutura de jobs em segundo plano. antes indo para produção, caso contrário sua integração deixará de receber eventos silenciosamente.

Webhooks e Eventos

Webhooks são a forma como uma API de e-mail moderna informa ao seu backend que algo aconteceu, em tempo real, sem que você precise perguntar. Em vez de consultarem /mensagens a cada 30 segundos (caro e lento), você se inscreve uma vez, e o provedor envia um payload JSON para seu endpoint toda vez que um novo e-mail chega, é lido, respondido ou excluído.

Os eventos aos quais você geralmente se inscreve são mail_received (uma nova mensagem chegou na caixa de entrada), mail_sent (uma mensagem de saída foi entregue com sucesso), email_aberto (o destinatário o abriu, se o rastreamento estiver ativado), link_email_clicado (o destinatário clicou em um link rastreado), e status_da_conta (a caixa de correio conectada precisa de reautenticação, por exemplo, após uma alteração de senha). Cada evento carrega contexto suficiente para que seus sistemas downstream reajam sem fazer chamadas de API adicionais.