Ir para o conteúdo
Documentação
E-mail recebido SendGrid

E-mail recebido SendGrid

Ver como Markdown

O Incoming Email Monitor do Status200 permite criar e resolver alertas com base em e-mails enviados para endereços únicos, específicos de cada monitor. Isso é útil para integrar sistemas legados, ferramentas de alerta ou qualquer serviço capaz de enviar e-mails.

A mesma configuração permite que workflows recebam e-mail: um workflow com o gatilho Incoming Email recebe um endereço próprio no mesmo domínio, e cada e-mail enviado a ele inicia o workflow. Veja Gatilhos.

Este guia explica como configurar o SendGrid Inbound Parse para encaminhar e-mails recebidos para a sua instância auto-hospedada do Status200. O Status200 Cloud não precisa de nada disso: os endereços funcionam de imediato.

Antes de começarUma conta no SendGrid, um domínio e um endereço HTTPS público.ConfiguraçãoSete passos, do registro MX a um e-mail de teste.Variáveis de ambienteAs três configurações e seus valores padrão.Solução de problemasE-mails que nunca chegam e webhooks que falham.

Como funciona

sequenceDiagram participant Sender as Servidor de<br/>e-mail remetente participant SendGrid as SendGrid<br/>Inbound Parse participant Status200 as Status200 Sender->>SendGrid: E-mail para<br/>o endereço do<br/>monitor (seu<br/>registro MX) SendGrid->>Status200: POST …/sendgrid/YOUR_SECRET Status200->>Status200: Associar o<br/>endereço a<br/>um monitor ou<br/>a um workflow Status200-->>SendGrid: 200 OK

Como um e-mail chega a um monitor

  1. Você cria um Incoming Email Monitor no Status200
  2. O Status200 gera um endereço de e-mail único para esse monitor (por exemplo, monitor-abc123@inbound.yourdomain.com)
  3. Quando um e-mail é enviado para esse endereço, o SendGrid o recebe e o encaminha ao Status200 por webhook
  4. O Status200 avalia o e-mail de acordo com os critérios que você configurou para criar ou resolver alertas

Pré-requisitos

  • Uma conta no SendGrid com acesso ao Inbound Parse
  • Um domínio que você controle, com acesso às configurações de DNS
  • Um endpoint HTTPS público que encaminhe os webhooks do SendGrid para a sua instância do Status200

Acesso de rede

No Inbound Parse, é o SendGrid que abre a conexão com o Status200. Permitir apenas o acesso de saída à internet a partir do Status200 não basta.

DireçãoDestinoProtocolo / portaFinalidade
SendGrid → Status200https://your-oneuptime-domain.com/incoming-email/sendgrid/YOUR_SECRETHTTPS / TCP 443Entregar o e-mail analisado como um POST multipart.
Servidores de e-mail remetentes → SendGridmx.sendgrid.net, escolhido pelo registro MX público do seu domínio de entradaSMTP / TCP 25Receber o e-mail no SendGrid; esta conexão não vai para o seu servidor do Status200.
Status200 → SendGrid, apenas quando o envio de e-mail pelo provedor SendGrid estiver configurado à parteapi.sendgrid.comHTTPS / TCP 443Enviar e-mails de notificação pela Mail Send API.

Publique o DNS do nome de host do webhook e sirva um certificado confiável para clientes públicos. Uma implantação privada do Status200 pode expor apenas o caminho do webhook por meio de um proxy reverso ou gateway públicos que alcancem o Status200 internamente. Preserve o caminho, o segredo, o tipo de conteúdo e o corpo multipart da requisição, e deixe o POST passar sem login interativo nem desafio do navegador. O servidor do Status200 não precisa de um listener SMTP de entrada. Veja a configuração do Inbound Parse no SendGrid.

Defina INBOUND_EMAIL_WEBHOOK_SECRET com um valor aleatório forte e substitua YOUR_SECRET na URL por esse valor. A rota exige o último segmento do caminho, e o Status200 só aceita um e-mail quando esse segmento é o segredo. Enquanto o segredo não estiver definido, todo e-mail é recusado com 503, que o SendGrid tenta de novo por até três dias. Mantenha em sigilo a URL completa e os endereços de e-mail dos monitores, inclusive nos logs do proxy. Atualmente o Status200 não valida os cabeçalhos assinados do Inbound Parse do SendGrid nem tokens OAuth. Se você precisa desses mecanismos, configure um gateway que os valide antes de encaminhar à URL completa, seguindo a documentação do SendGrid sobre segurança de webhooks.

O SendGrid não fornece uma lista confiável de IPs de origem estáticos para o Inbound Parse. Os IPs de envio de e-mail dele e os endereços resolvidos para mx.sendgrid.net não são uma lista de permissões para o webhook. Siga as orientações do SendGrid sobre firewall em vez de fixar um resultado de DNS atual.

O Inbound Parse é separado do envio de e-mail de saída. Receber os e-mails dos monitores não exige que o Status200 chame a API do SendGrid. Se você também escolher o SendGrid para enviar notificações, permita a resolução de DNS e o HTTPS de saída para api.sendgrid.com; o Mail Send não precisa de nenhum callback de entrada para o envio. Se usar SMTP, permita o servidor e a porta SMTP configurados no Status200.

Instruções de configuração

  1. Escolha o seu domínio de entrada

    Escolha um subdomínio dedicado a receber e-mails para o Status200, como inbound.yourdomain.com, email.yourdomain.com ou monitor.yourdomain.com. Ele é usado apenas para e-mails destinados a monitores e workflows do Status200, então nenhuma caixa de correio sua fica nele.

  2. Aponte o registro MX dele para o SendGrid

    Adicione um registro MX que encaminhe os e-mails do subdomínio para o SendGrid:

    TipoHost/NomePrioridadeValor
    MXinbound10mx.sendgrid.net

    Se o seu domínio é example.com e você usa inbound.example.com, o registro fica assim:

    inbound.example.com.  IN  MX  10  mx.sendgrid.net.

    Alterações de DNS podem levar até 48 horas para se propagar, mas normalmente terminam em poucas horas.

  3. Autentique o domínio no SendGrid

    O domínio de recebimento precisa pertencer a um dos seus domínios autenticados no SendGrid. No painel do SendGrid, vá em Settings > Sender Authentication, clique em Authenticate Your Domain e adicione os registros DNS solicitados (registros CNAME para DKIM).

  4. Adicione o webhook do Inbound Parse

    No painel do SendGrid, vá em Settings > Inbound Parse e clique em Add Host & URL. Preencha como abaixo e clique em Add:

    CampoValor
    Receiving DomainSeu subdomínio de entrada (por exemplo, inbound.yourdomain.com)
    Destination URLhttps://your-oneuptime-domain.com/incoming-email/sendgrid/YOUR_SECRET
    Check incoming emails for spamOpcional – ative se quiser
    Send raw, full MIME messageDeixe desmarcado (não é necessário)
    POST the raw, full MIME messageDeixe desmarcado (não é necessário)

  5. Configure o Status200

    Defina as variáveis de e-mail recebido, com o mesmo segredo da Destination URL:

    Docker Compose

    config.envBash 
    INBOUND_EMAIL_PROVIDER=SendGrid
INBOUND_EMAIL_DOMAIN=inbound.yourdomain.com
INBOUND_EMAIL_WEBHOOK_SECRET=replace-with-a-strong-random-secret

    Kubernetes

    values.yamlYAML 
    inboundEmail:
  provider: "SendGrid"
  domain: "inbound.yourdomain.com"
  webhookSecret: "replace-with-a-strong-random-secret"

    INBOUND_EMAIL_WEBHOOK_SECRET é obrigatória: o Status200 recusa todo e-mail enquanto ela estiver vazia ou ainda for um marcador desta página. openssl rand -hex 32 gera um valor aleatório longo.

    Depois aplique-as: execute npm run start no Docker Compose, o que recria os contêineres com os novos valores, ou atualize a release do Helm no Kubernetes.

  6. Crie um monitor Incoming Email

    Crie um monitor Incoming Email. A página Visão geral dele mostra o endereço, como monitor-abc123def456@inbound.yourdomain.com, e os critérios dele decidem quais e-mails criam um alerta e quais o resolvem.

    Os workflows usam o mesmo domínio. Adicione o gatilho Incoming Email a um workflow e clique nele: o endereço (workflow-…@inbound.yourdomain.com) aparece no topo das configurações dele. Enquanto as variáveis de e-mail recebido acima não estiverem definidas, o gatilho informa que o servidor não está preparado para receber e-mail.

  7. Envie um e-mail de teste

    Envie um e-mail para o endereço do monitor, com um assunto que corresponda aos critérios dele. O resumo do monitor mostra o e-mail, e um alerta é criado quando os critérios correspondem.

Referência das variáveis de ambiente

VariávelValor do HelmDescriçãoObrigatóriaPadrão
INBOUND_EMAIL_PROVIDERinboundEmail.providerO provedor de e-mail recebido. O SendGrid é o único.NãoSendGrid
INBOUND_EMAIL_DOMAINinboundEmail.domainO subdomínio configurado para e-mails recebidos. O recebimento de e-mail fica desligado até que ele seja definido.SimVazio
INBOUND_EMAIL_WEBHOOK_SECRETinboundEmail.webhookSecretSegredo ao qual o último segmento da URL do webhook deve corresponder: /incoming-email/sendgrid/YOUR_SECRET. Todo e-mail é recusado enquanto ele estiver vazio ou for um marcador.SimVazio

Em que um monitor Incoming Email pode se basear – o assunto, o remetente, o corpo, o destinatário e se um e-mail chegou a tempo – está em Tipos de filtro disponíveis.

Solução de problemas

Os e-mails não estão sendo recebidos
  1. Verifique a propagação do DNS: dig MX inbound.yourdomain.com deve retornar mx.sendgrid.net.
  2. Confira as configurações do Inbound Parse no SendGrid: no painel do SendGrid, em Settings > Inbound Parse, confira o seu domínio e a URL do webhook.
  3. Verifique os logs do Status200: procure as requisições do webhook de e-mail recebido, e qualquer erro, nos logs do serviço app do Status200. O SendGrid não guarda logs detalhados do Inbound Parse, então esses logs são o registro do que chegou.
Os webhooks estão falhando
  1. Verifique a rota pública do webhook: a URL completa, incluindo o segredo, precisa chegar ao Status200 pela internet. A URL sem o último segmento secreto não corresponde à rota.
  2. Verifique as regras do firewall: permita requisições HTTPS POST para o caminho do webhook sem redirecionamentos de login nem desafios do navegador, e não use os IPs de envio de e-mail do SendGrid como lista de origens permitidas do webhook.
  3. Verifique o certificado SSL: use para o nome de host do webhook um certificado válido e confiável publicamente, e inclua a cadeia de certificados dele.
  4. Verifique o segredo do webhook: a Destination URL deve terminar com o valor de INBOUND_EMAIL_WEBHOOK_SECRET. Enquanto a variável estiver vazia ou for um marcador, todo e-mail é recusado com 503, e o log do serviço app avisa isso ao iniciar; um e-mail enviado para uma URL que termina com qualquer outra coisa é recusado com 403.
O monitor não cria alertas
  1. Confira os critérios: verifique se os seus critérios de criação de alertas correspondem ao conteúdo do e-mail, e teste primeiro com textos exatos antes de usar padrões.
  2. Verifique o monitor: confirme que ele não está desativado e que o tipo dele é Incoming Email.
  3. Revise o resumo do monitor: verifique se o e-mail foi recebido e processado, e leia os logs de avaliação para ver como os critérios corresponderam.
O gatilho informa que o servidor não está preparado para receber e-mail

INBOUND_EMAIL_DOMAIN está vazia no servidor. Defina-a, aplique a alteração e abra de novo o gatilho do workflow.

Boas práticas de segurança

  1. Use HTTPS: use sempre HTTPS no endpoint do seu webhook
  2. Segredo do webhook: use para INBOUND_EMAIL_WEBHOOK_SECRET um valor aleatório longo e só seu, no fim da URL do seu webhook (por exemplo, /incoming-email/sendgrid/your-secret): é ele que distingue os e-mails do SendGrid dos de qualquer outra pessoa
  3. Verificação do domínio: verifique o seu domínio no SendGrid para mais segurança de e-mail
  4. Restrinja o acesso: crie monitores apenas para origens de e-mail confiáveis
  5. Monitore os logs: revise regularmente os logs de e-mails recebidos em busca de atividade suspeita

Próximos passos

Incoming Email MonitorCritérios, formatos de endereço e exemplos.Gatilhos de workflowInicie um workflow a partir de um e-mail.Acesso à rede privadaO que o seu servidor pode alcançar na sua própria rede.ArquiteturaOnde o webhook chega em uma instalação auto-hospedada.