# Runbook: e-mail via Twilio SendGrid + SMS OTP via Twilio (2026-07-23)

Escopo de deploy: SOMENTE core-api (HML e PRD). Sem migration. Não toca
pix/spb/sta. Design: `docs/plans/2026-07-23-emails-twilio-sendgrid-sms-otp-design.md`.

## Já executado nesta sessão (23/07)

- Secrets criados no Secrets Manager:
  - `monetarie/homolog/twilio/auth_token` (credencial TEST do Twilio; ARN sufixo `-CVWuTN`)
  - `monetarie/prod/twilio/auth_token` (credencial LIVE; ARN sufixo `-ZRwLLK`)
- Execution roles atualizadas (whitelist de ARNs exatos):
  - `monetarie-ecs-execution-homolog` / policy `monetarie-ecs-secrets-homolog` ganhou o ARN do token HML
  - `monetarie-ecs-execution-prod` / policy `monetarie-ecs-secrets-prod` ganhou o ARN do token PRD

## Passo 1: deploy do core-api (fase SMS, e-mail continua como está)

Build/deploy padrão do core-api (tag imutável, digest match HML→PRD). Na nova
revisão da task-def, ADICIONAR:

HML (`monetarie-core-api-homolog`):

```
environment:
  TWILIO_ACCOUNT_SID = AC15ec8682d1b7d5d134c5c01eb04d906a   (TEST)
  TWILIO_FROM_NUMBER = +15005550006    (numero magico; test creds SO aceitam esse From)
  TWILIO_ENABLED     = true
  BANKING_BASE_URL   = https://ib-h.monetarie.com
  EMAIL_FROM         = noreply@monetarie.com   (hoje esta nao-responda@monetarie.com)
secrets:
  TWILIO_AUTH_TOKEN  = arn ...:secret:monetarie/homolog/twilio/auth_token-CVWuTN
```

PRD (`monetarie-core-api-prod`):

```
environment:
  TWILIO_ACCOUNT_SID = AC8b7c12114237d923be6c729468f7b706   (LIVE)
  TWILIO_FROM_NUMBER = +14143009694   (unico numero da conta; SMS ok)
  TWILIO_ENABLED     = true
  BANKING_BASE_URL   = https://ib.monetarie.com
  EMAIL_FROM         = noreply@monetarie.com
secrets:
  TWILIO_AUTH_TOKEN  = arn ...:secret:monetarie/prod/twilio/auth_token-ZRwLLK
```

`SMS_TRANSPORT` não precisa ser setado (default do runtime = twilio).
`EMAIL_TRANSPORT` permanece `ses` nesta fase (flip no Passo 2).

Validação pós-swap:

- HML: disparar um OTP (MFA SMS ou onboarding phone) e conferir no log
  `[Notifier.Sms] Twilio SMS delivered (sid=SM...)`. Com credencial TEST o
  Twilio ACEITA e não entrega nada (por design; custo zero).
- PRD: em produção não existe teste; validar com 1 SMS real no telefone do
  dono (MFA de um usuário com o telefone dele) e conferir sid + recebimento.

## Passo 2: flip do e-mail para SendGrid (BLOQUEADO na API key do cliente)

Pré-condições (pedido ao cliente, abaixo):

1. API key do Twilio SendGrid (formato `SG.`, permissão Mail Send).
2. Domínio `monetarie.com` autenticado no SendGrid (CNAMEs DKIM/SPF no DNS)
   e remetente `noreply@monetarie.com` válido.

Execução:

```
aws secretsmanager create-secret --name monetarie/homolog/sendgrid/api_key --secret-string 'SG....'
aws secretsmanager create-secret --name monetarie/prod/sendgrid/api_key    --secret-string 'SG....'
# adicionar os 2 ARNs novos nas policies monetarie-ecs-secrets-{homolog,prod}
# nova revisao da task-def core-api:
#   environment: EMAIL_TRANSPORT = sendgrid
#   secrets:     SENDGRID_API_KEY = <arn do respectivo ambiente>
```

Fail-closed: `EMAIL_TRANSPORT=sendgrid` sem `SENDGRID_API_KEY` derruba o boot
de propósito; nunca aplicar o env sem a secret na mesma revisão.

Validação: OTP de onboarding por e-mail em HML/PRD chega na caixa de entrada
com remetente `noreply@monetarie.com` (conferir SPF/DKIM pass nos headers).

Rollback: `EMAIL_TRANSPORT=ses` (volta ao estado atual) ou `smtp`.

## Passo 3 (opcional, junto do Passo 2): alertas do SPB por SendGrid SMTP

O `BacenGateway.Alerts.EmailDelivery` (spb-api) usa gen_smtp puro; basta env
na task-def do spb-api (SEM mudança de código):

```
SMTP_HOST=smtp.sendgrid.net  SMTP_PORT=587  SMTP_USER=apikey
SMTP_PASS=<SG key>           SMTP_FROM=noreply@monetarie.com
```

Respeitar a regra: NUNCA deploy/restart de spb com o dono operando money-path.

## Pedido ao cliente (copiar/colar)

Para concluirmos a troca do provedor de e-mails para o Twilio, precisamos de
dois itens do console de vocês (Twilio SendGrid):

1. Uma API key do Twilio SendGrid com permissão de envio (Mail Send). No
   console: SendGrid, Settings, API Keys, Create API Key. O par Account SID e
   Auth Token que vocês enviaram vale para SMS e voz, mas o produto de e-mail
   do Twilio (SendGrid) usa uma chave própria no formato SG.
2. Autenticação do domínio monetarie.com no SendGrid (Settings, Sender
   Authentication, Authenticate Your Domain). O SendGrid vai gerar 3 registros
   CNAME para publicarmos no DNS do monetarie.com; com isso os e-mails saem
   assinados (DKIM/SPF) em nome de noreply@monetarie.com, sem cair em spam.

Enquanto isso, já deixamos o envio de SMS (código de verificação por telefone)
preparado com as credenciais que vocês enviaram.

## Observações

- Deliverability de SMS +55 a partir do número US +14143009694 funciona, mas
  para volume o recomendado é Messaging Service com sender BR registrado.
- O auth token live foi compartilhado em chat; recomendável rotacionar no
  console Twilio após o cadastro no Secrets Manager (trocar a secret junto).
- Restos de `vulci.com.br` fora de código vivo (não bloqueiam nada): hosts
  mortos em `core/e2e/playwright.config.ts` e bundle legado commitado em
  `sta/backend/priv/static/assets/` (candidato a remoção pelo time do STA).