E-mail

O Studio envia convites de workspace, verificação de e-mail, redefinições de senha e notificações. Configure pelo menos um provedor.

Sem nenhum provedor configurado, nada é enviado e nada falha — o serviço de e-mail registra uma única linha de log com o destinatário, o assunto e o remetente, e então informa sucesso. Em uma implantação de produção, isso significa que convites de workspace simplesmente nunca chegam. O corpo da mensagem não é registrado, então um e-mail perdido desse jeito não pode ser recuperado a partir dos logs.

Escolha do provedor

Não existe uma flag de provedor. Todo provedor cujas variáveis estiverem definidas fica ativo, e o serviço de e-mail tenta cada um nesta ordem fixa, passando para o próximo apenas quando o anterior falha:

Resend → AWS SES → SMTP → Azure Communication Services → Gmail

Ou seja: o primeiro provedor configurado cuida do tráfego normal, e os demais funcionam como failover automático. Configurar um é o caso simples; configurar dois lhe dá um caminho de reserva, ao custo de o e-mail ocasionalmente sair de um remetente diferente.

Configurações compartilhadas

Variável	Descrição
`FROM_EMAIL_ADDRESS`	Endereço do remetente, por exemplo `Studio <noreply@example.com>`
`EMAIL_DOMAIN`	Domínio de reserva quando `FROM_EMAIL_ADDRESS` não está definido — envia como `noreply@EMAIL_DOMAIN`
`EMAIL_VERIFICATION_ENABLED`	Defina `true` para exigir verificação de e-mail no cadastro

O endereço do remetente precisa ser um que seu provedor esteja autorizado a usar. Uma divergência aqui é a causa mais comum de e-mails que o provedor aceita e depois descarta ou marca como spam mais adiante.

Provedores

A opção mais simples se você não tem infraestrutura de e-mail própria.

RESEND_API_KEY=re_...
FROM_EMAIL_ADDRESS="Studio <noreply@yourdomain.com>"

Verifique seu domínio de envio no painel do Resend e adicione os registros DNS que ele indicar antes de enviar em produção.

AWS_SES_REGION=us-east-1
FROM_EMAIL_ADDRESS="Studio <noreply@yourdomain.com>"

As credenciais são resolvidas pela cadeia padrão de provedores da AWS — variáveis de ambiente, configuração compartilhada, task role do ECS/EKS (IRSA), instance profile do EC2 ou SSO. No EKS, associe uma role IRSA com ses:SendEmail e ses:SendRawEmail e não defina chave nenhuma.

Contas novas do SES ficam no sandbox, que só permite envio para endereços verificados. Convites para seu time vão falhar até você solicitar acesso de produção. Verifique também o domínio de envio e configure DKIM.

Funciona com qualquer relay — Postfix, SendGrid, Mailgun, o relay SMTP do Google Workspace, ou MailHog para testes locais.

SMTP_HOST=smtp.example.com
SMTP_PORT=587          # 465 implicit TLS, 587 STARTTLS, 25 plain
SMTP_USER=apikey       # omit for unauthenticated relays
SMTP_PASS=...          # omit for unauthenticated relays
# SMTP_SECURE=true     # only for implicit TLS. Leave unset on 587 — it is
                       # automatic on 465, and forcing it on a STARTTLS port fails to connect
FROM_EMAIL_ADDRESS="Studio <noreply@yourdomain.com>"

Para o Google Workspace sem uma conta de serviço:

SMTP_HOST=smtp-relay.gmail.com
SMTP_PORT=587

O relay precisa estar configurado no console de administração do Workspace para aceitar e-mails do IP de saída da sua implantação.

AZURE_ACS_CONNECTION_STRING=endpoint=https://...;accesskey=...
FROM_EMAIL_ADDRESS="Studio <noreply@yourdomain.com>"

Provisione um Email Communication Service, conecte um domínio verificado e então vincule-o ao recurso do Communication Service. O endereço do remetente precisa pertencer ao domínio vinculado.

A GCP não tem serviço próprio de e-mail transacional, então o caminho nativo do Google é a API do Gmail com um remetente do Google Workspace.

GMAIL_CREDENTIALS_JSON='{"type":"service_account",...}'
GMAIL_SENDER=noreply@yourdomain.com
FROM_EMAIL_ADDRESS="Studio <noreply@yourdomain.com>"

Configuração:

Crie uma conta de serviço e baixe a chave JSON dela.
No console de administração do Workspace → Security → Access and data control → API controls → Domain-wide delegation → Add new, adicione o client_id da conta de serviço com o escopo https://www.googleapis.com/auth/gmail.send.
Defina GMAIL_SENDER como o usuário do Workspace que a conta de serviço vai personificar.

FROM_EMAIL_ADDRESS precisa coincidir com GMAIL_SENDER ou com um dos aliases registrados dele. O Gmail reescreve endereços de origem que não reconhece, então uma divergência gera e-mails que são enviados com sucesso, mas chegam com o endereço errado.

O Gmail limita o envio a cerca de 2.000 mensagens por dia por usuário — mais que suficiente para convites e verificação na maioria das implantações. Se você precisar de mais, troque para o relay SMTP do Workspace ou para o Resend; ambos são mudanças apenas de configuração.

Mantenha o JSON em uma única linha ao colá-lo em um arquivo de values:

jq -c . service-account-key.json

Kubernetes

As credenciais de e-mail são segredos. Forneça-as pelo seu cofre de segredos em vez de valores em texto puro:

app:
  env:
    FROM_EMAIL_ADDRESS: "Studio <noreply@yourdomain.com>"
    RESEND_API_KEY: "re_..."      # via External Secrets or an existing Secret

Nos modos padrão e External Secrets, as chaves de app.env são escritas em um Secret gerenciado pelo chart e montadas via envFrom, então os valores não aparecem nas especificações dos pods. Um segredo commitado no values.yaml continua sendo um segredo no seu histórico do git — passe-o por External Secrets ou por um Secret criado previamente.

Verificação

Convide um usuário para um workspace pelas configurações do workspace e acompanhe os logs da aplicação:

kubectl logs -n studio -l app.kubernetes.io/component=app --tail=100 | grep -i mail

O que você vê	Significado
Uma única linha de log com destinatário, assunto e remetente, e nenhuma entrega	Nenhum provedor está configurado — o serviço de e-mail não fez nada
Um erro da API do provedor	Problema de credenciais ou de endereço do remetente; o erro diz qual
Sucesso, mas nada chega	Entregue ao provedor — verifique o painel do provedor, depois filtragem de spam, SPF e DKIM

Resolução de problemas

"Delegation denied" / unauthorized_client (Gmail) — a entrada de delegação em todo o domínio está ausente ou tem o client ID ou o escopo errado. Confira novamente a entrada no console de administração contra o client_id do JSON da conta de serviço e confirme que o escopo é exatamente https://www.googleapis.com/auth/gmail.send.

E-mail rejeitado com erro de endereço de origem — o remetente não está autorizado para o domínio verificado do provedor. Alinhe FROM_EMAIL_ADDRESS com o domínio verificado (e com GMAIL_SENDER no caminho do Gmail).

O SES rejeita destinatários — a conta ainda está no sandbox do SES. Solicite acesso de produção.

O e-mail cai no spam — configure SPF, DKIM e DMARC para o seu domínio de envio. Isso depende do seu DNS, não do Studio.

Nada acontece e nenhum erro aparece — nenhum provedor está configurado. Os logs vão mostrar uma linha com o destinatário e o assunto.

Common Questions

Todo provedor configurado fica ativo e é tentado em uma ordem fixa — Resend, AWS SES, SMTP, Azure Communication Services, Gmail — e o próximo só é usado se o anterior falhar. O primeiro provedor configurado cuida do tráfego normal; os demais funcionam como failover automático.

O Gmail reescreve endereços de origem que não reconhece. FROM_EMAIL_ADDRESS precisa coincidir com GMAIL_SENDER ou com um dos aliases registrados desse usuário.

Sim. As credenciais são resolvidas pela cadeia padrão de provedores da AWS, então uma role IRSA no EKS ou um instance profile no EC2 funcionam — defina apenas AWS_SES_REGION e conceda ses:SendEmail e ses:SendRawEmail.

Normalmente sim — ele não precisa de conta de serviço nem de delegação em todo o domínio, apenas SMTP_HOST=smtp-relay.gmail.com na porta 587 e uma entrada de allowlist para o seu IP de saída no console de administração do Workspace. Use o caminho da API do Gmail quando você não puder liberar um IP de saída estável.