Seslock Holmes

O AWS SES emite um evento para cada coisa que acontece com um e-mail: entrega, bounce, reclamação, rejeição. Só que esses eventos chegam soltos. Para quem está no suporte, a informação que sobra é a pior possível: “o e-mail não chegou”.

Sem uma leitura consolidada não dá para separar as causas. Endereço digitado errado, domínio sem registro MX e falha de autenticação DMARC produzem sintomas parecidos e exigem correções completamente diferentes.

E bounce alto não é só incômodo operacional: ele degrada a reputação de envio. Quanto pior a reputação, mais mensagens legítimas caem em spam — até o provedor começar a bloquear o envio.

AWS SES emits an event for everything that happens to an email: delivery, bounce, complaint, rejection. Those events arrive scattered. For whoever is on support duty, the only information left is the worst possible one: “the email didn't arrive”.

Without a consolidated view you cannot separate causes. A mistyped address, a domain with no MX record and a DMARC authentication failure produce similar symptoms and require completely different fixes.

And a high bounce rate is not just an operational annoyance: it degrades sending reputation. The worse the reputation, the more legitimate mail lands in spam — until the provider starts blocking delivery altogether.

Construí um painel somente-leitura sobre os eventos já armazenados em Supabase/PostgreSQL. A regra central: o dashboard nunca cria, edita ou remove evento de e-mail — ele só lê, e a leitura depende de RLS e autenticação no banco.

• Indicadores calculados no banco, via RPC, para refletir o período inteiro filtrado em vez de uma amostra carregada no navegador.
• Investigação por eixo: destinatário, remetente, provedor (domínio do destinatário) ou diagnóstico de bounce, com sugestões de e-mails semelhantes quando não há correspondência exata.
• Rastreamento cronológico da mensagem, com origem/IP, tempo de processamento, resposta SMTP, tipo e subtipo de bounce e diagnostic code direto no card.
• Relatórios agendados com filtros próprios e múltiplos destinatários, disparados por um workflow do GitHub Actions a cada 15 minutos e reforçados por um cron diário na Vercel.
• Compartilhamento público somente-leitura, com os filtros travados e protegido por token de 256 bits, para quem precisa ver o painel sem ter conta.

I built a read-only panel on top of the events already stored in Supabase/PostgreSQL. The core rule: the dashboard never creates, edits or deletes an email event — it only reads, and that read depends on RLS and authentication in the database.

• Metrics computed in the database, through RPCs, so they reflect the entire filtered period instead of a sample loaded in the browser.
• Investigation by axis: recipient, sender, provider (recipient domain) or bounce diagnosis, with similar-address suggestions when there is no exact match.
• Chronological message tracing, exposing source/IP, processing time, SMTP response, bounce type and subtype and the diagnostic code right on the card.
• Scheduled reports with their own filters and multiple recipients, fired by a GitHub Actions workflow every 15 minutes and backed by a daily Vercel cron.
• Public read-only sharing, with filters locked and protected by a 256-bit token, for people who need to see the panel without an account.

Um painel que lê e-mail de cliente é um painel que precisa errar pouco. As decisões de acesso vieram antes das telas:

• O frontend usa apenas a URL e a chave pública do Supabase — nunca uma service key.
• Perfis de acesso: toda conta é viewer ou manager. Viewers só visualizam; managers também criam e editam agendamentos e links. Conta nova começa como viewer.
• Log de auditoria somente-leitura, visível a qualquer usuário autenticado, com toda ação administrativa: criação, edição, pausa, exclusão, disparo forçado e resultado dos envios.
• Nos links públicos, a lista de atividade recente vem desligada por padrão, porque ela expõe e-mail de destinatário. O link tem validade opcional e pode ser regenerado ou revogado.

A panel that reads customer email is a panel that needs a small blast radius. Access decisions came before the screens:

• The frontend only uses the Supabase URL and publishable key — never a service key.
• Access profiles: every account is a viewer or a manager. Viewers only read; managers also create and edit schedules and links. New accounts start as viewers.
• Read-only audit log, visible to any authenticated user, covering every administrative action: creation, edit, pause, deletion, forced runs and the outcome of each automated send.
• On public links the recent-activity list is off by default, because it exposes recipient addresses. Links have an optional expiry and can be regenerated or revoked.

• Indicador calculado no cliente mente. Enquanto a taxa de bounce saía de uma amostra paginada, ela mudava conforme a rolagem. Empurrar o cálculo para RPC no banco resolveu o número e a confiança nele.
• Bounce não é um número, é uma lista de causas. O painel só ficou útil quando passou a separar subtipo — suppressed, general, mailbox full, content rejected, undetermined.
• Compartilhar exige desenhar o que não vai junto. A parte difícil do link público não foi gerar o token: foi decidir que a atividade recente fica fora por padrão.

• A metric computed in the client lies. While the bounce rate came from a paginated sample, it changed as you scrolled. Pushing the computation into a database RPC fixed both the number and the trust in it.
• A bounce is not a number, it is a list of causes. The panel only became useful once it separated subtypes — suppressed, general, mailbox full, content rejected, undetermined.
• Sharing means designing what stays out. The hard part of the public link was not generating the token: it was deciding that recent activity is excluded by default.