> ## Documentation Index
> Fetch the complete documentation index at: https://www.notifuse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SMTP

> Configure o SMTP como provedor de email no Notifuse, com Basic Auth ou OAuth2.

A integração SMTP conecta ao Notifuse qualquer serviço de email compatível com SMTP, com autenticação por senha ou com OAuth2 para Microsoft 365 e Gmail.

## Configuração

Vá em **Configurações** → **Integrações**, clique em **Adicionar integração** e escolha **SMTP** em **Envio de emails**. O formulário abre em página inteira.

### Configurações básicas

| Campo                 | Descrição                                                                                                                | Exemplo               |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------- |
| **Nome**              | Nome de exibição desta configuração SMTP                                                                                 | `Company SMTP`        |
| **Host**              | Nome do host do servidor SMTP                                                                                            | `smtp.gmail.com`      |
| **Porta**             | Número da porta do servidor SMTP: 587 para STARTTLS, 465 para TLS desde o primeiro byte, 25 sem criptografia             | `587`                 |
| **Criptografia**      | O interruptor **Usar TLS**. Ligado: STARTTLS, ou TLS desde o primeiro byte na porta 465. Desligado: texto simples        | `On`                  |
| **Nome do host EHLO** | Nome do host enviado com o comando SMTP EHLO. Quando vazio, usa o host. Útil quando um servidor recusa `EHLO localhost`. | `mail.yourdomain.com` |

### Tipo de autenticação

Escolha uma de duas opções em **Método**, no painel **Autenticacao**:

| Opção               | Descrição              | Caso de uso                                   |
| ------------------- | ---------------------- | --------------------------------------------- |
| **Usuário e senha** | Autenticação básica    | A maioria dos servidores SMTP, senhas de app  |
| **OAuth2**          | Autenticação por token | Microsoft 365, Gmail (obrigatório desde 2024) |

---

## Autenticação básica

Para servidores SMTP que aceitam senha, ou serviços que oferecem senhas de app.

| Campo               | Descrição                                                                                   | Exemplo                |
| ------------------- | ------------------------------------------------------------------------------------------- | ---------------------- |
| **Nome de Usuário** | Nome de usuário para autenticação. Deixe vazio para um servidor que aceita emails sem login | `your-email@gmail.com` |
| **Senha**           | Senha de autenticação                                                                       | `your-app-password`    |

---

## Autenticação OAuth2

O Microsoft 365 e o Gmail descontinuaram a autenticação básica, então exigem OAuth2.

### OAuth2 do Microsoft 365

![Microsoft 365](https://www.notifuse.com/docs/assets/microsoft-365-icon.svg)

O Microsoft 365 usa o **fluxo Client Credentials** para a autenticação entre servidores.

#### Pré-requisitos

- Conta Microsoft 365 Business (não uma conta pessoal do Outlook.com)
- Acesso de administrador ao Azure AD
- Acesso de administrador ao Exchange Online

#### Etapa 1: registre o aplicativo no Azure AD

1. Vá em [Azure Portal](https://portal.azure.com) → **Azure Active Directory** → **App registrations**
2. Clique em **New registration**
3. Digite um nome (por exemplo, "Notifuse SMTP")
4. Selecione **Accounts in this organizational directory only** (Single tenant)
5. Clique em **Register**
6. Anote o **Application (client) ID** e o **Directory (tenant) ID**

#### Etapa 2: crie um segredo do cliente

1. No registro do seu aplicativo, vá em **Certificates & secrets**
2. Clique em **New client secret**
3. Adicione uma descrição e escolha o prazo de validade
4. Clique em **Add**
5. **Copie o valor do segredo imediatamente** (ele não será exibido de novo)

#### Etapa 3: adicione a permissão de API

1. Vá em **API permissions** → **Add a permission**
2. Selecione **APIs my organization uses**
3. Procure **Office 365 Exchange Online**
4. Selecione **Application permissions**
5. Marque **SMTP.SendAsApp**
6. Clique em **Add permissions**
7. Clique em **Grant admin consent for \[Your Organization]**

#### Etapa 4: registre a entidade de serviço no Exchange Online

Esta etapa costuma ser esquecida, e a autenticação falha sem ela. Conecte-se ao PowerShell do Exchange Online:

```powershell
# Install module if needed
Install-Module -Name ExchangeOnlineManagement

# Connect to Exchange Online
Connect-ExchangeOnline -UserPrincipalName admin@yourdomain.com

# Register the service principal
New-ServicePrincipal -AppId <Application-Client-ID> -ObjectId <Object-ID>
```

> [!WARNING]
>
> O `ObjectId` precisa vir de **Enterprise Applications**, e não de App Registrations.
>
> Para encontrar o Object ID correto:
>
> 1. Vá em Azure Portal → **Microsoft Entra ID** → **Enterprise Applications**
> 2. Procure o nome do seu aplicativo
> 3. Copie o **Object ID** da página Overview

#### Etapa 5: conceda a permissão na caixa de correio

Conceda à entidade de serviço a permissão de enviar como uma caixa de correio específica:

```powershell
# Grant full access to the mailbox
Add-MailboxPermission -Identity "sender@yourdomain.com" -User <Object-ID> -AccessRights FullAccess

# Grant send-as permission
Add-RecipientPermission -Identity "sender@yourdomain.com" -Trustee <Object-ID> -AccessRights SendAs
```

#### Etapa 6: ative o SMTP AUTH na caixa de correio

Ative o SMTP AUTH na caixa de correio de envio, no Microsoft 365 Admin Center ou pelo PowerShell:

**Opção A: Microsoft 365 Admin Center**

1. Vá em **Users** → **Active users**
2. Selecione o usuário remetente
3. Clique na aba **Mail** → **Manage email apps**
4. Marque **Authenticated SMTP**
5. Clique em **Save changes**

**Opção B: PowerShell**

```powershell
# Enable SMTP AUTH for the mailbox
Set-CASMailbox -Identity "sender@yourdomain.com" -SmtpClientAuthenticationDisabled $false
```

> [!WARNING]
>
> Se os **Security Defaults** estiverem ativados no seu tenant do Microsoft Entra, o SMTP AUTH fica bloqueado para a organização inteira. Talvez você precise desativar os Security Defaults ou usar políticas de Conditional Access no lugar deles.

#### Etapa 7: configure no Notifuse

| Campo                            | Valor                                                     |
| -------------------------------- | --------------------------------------------------------- |
| **Host**                         | `smtp.office365.com`                                      |
| **Porta**                        | `587`                                                     |
| **Usar TLS**                     | `On`                                                      |
| **Método**                       | **OAuth2**                                                |
| **Provedor OAuth2**              | **Microsoft 365 / Office 365**                            |
| **Endereço da caixa de correio** | Email do remetente (por exemplo, `sender@yourdomain.com`) |
| **ID do tenant**                 | O Directory (tenant) ID do Azure AD                       |
| **Client ID**                    | O Application (client) ID do Azure                        |
| **Client secret**                | O valor do segredo da etapa 2                             |

> [!WARNING]
>
> O **Endereço da caixa de correio** precisa ser a caixa de correio à qual você concedeu as permissões na etapa 5.

---

### OAuth2 do Gmail

![Gmail](https://www.notifuse.com/docs/assets/gmail-icon.svg)

O Gmail usa o **fluxo Refresh Token** para a autenticação.

#### Pré-requisitos

- Conta Google (Gmail pessoal ou Google Workspace)
- Acesso ao Google Cloud Console
- Um terminal com `curl` instalado

#### Etapa 1: crie um projeto no Google Cloud

1. Vá em [Google Cloud Console](https://console.cloud.google.com)
2. Crie um novo projeto ou selecione um existente
3. Ative a **Gmail API**:
   - Vá em **APIs & Services** → **Library**
   - Procure "Gmail API" e ative

#### Etapa 2: configure a tela de consentimento OAuth

1. Vá em **APIs & Services** → **OAuth consent screen**
2. Selecione o tipo de usuário **External** (ou Internal no Workspace)
3. Preencha as informações do app:
   - App name: "Notifuse" (ou o nome que preferir)
   - User support email: o seu email
   - Developer contact: o seu email
4. Clique em **Save and Continue**
5. Na página **Scopes**, clique em **Add or Remove Scopes**
6. Adicione o escopo: `https://mail.google.com/`
7. Clique em **Save and Continue**
8. Na página **Test users**, adicione o seu endereço do Gmail
9. Clique em **Save and Continue** para concluir o assistente

#### Etapa 3: publique o seu app (obrigatório para tokens de longa duração)

> [!WARNING]
>
> No modo "Testing", os refresh tokens expiram depois de **7 dias**. Publique o seu app para obter refresh tokens permanentes.

1. Vá em **APIs & Services** → **OAuth consent screen**
2. Clique em **Publish App**
3. Confirme clicando em **Confirm**

O status do app muda de "Testing" para "In production".

> [!NOTE]
>
> **Sem verificação do Google para uso pessoal**
>
> Publicar o seu app NÃO exige verificação do Google se:
>
> - Você tem menos de 100 usuários
> - Você o usa para fins pessoais ou internos
>
> Se aparecer um aviso de "unverified app" na autorização, clique em **Advanced** → **Go to \[App Name] (unsafe)** para continuar.

#### Etapa 4: crie as credenciais OAuth

1. Vá em **APIs & Services** → **Credentials**
2. Clique em **Create Credentials** → **OAuth client ID**
3. Selecione **Web application**
4. Dê um nome (por exemplo, "Notifuse SMTP")
5. Em **Authorized redirect URIs**, clique em **Add URI**
6. Digite: `http://localhost`
7. Clique em **Create**
8. Uma caixa de diálogo mostra o seu **Client ID** e o seu **Client Secret**: guarde os dois

#### Etapa 5: obtenha o código de autorização

Abra esta URL no navegador, com o seu Client ID no lugar de `YOUR_CLIENT_ID`:

```
https://accounts.google.com/o/oauth2/v2/auth?client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost&scope=https://mail.google.com/&response_type=code&access_type=offline&prompt=consent
```

**Parâmetros importantes da URL:**

- `scope=https://mail.google.com/`: obrigatório para o acesso SMTP
- `access_type=offline`: obrigatório para receber um refresh token
- `prompt=consent`: obriga o Google a retornar um novo refresh token

Depois que você faz login e concede a permissão, o navegador redireciona para algo como:

```
http://localhost/?code=4/0AQSTgQF...LONG_CODE...&scope=https://mail.google.com/
```

Copie o valor inteiro de `code` (tudo entre `code=` e `&scope`).

> [!TIP]
>
> Se o código contiver `%2F`, troque por `/` antes de usá-lo.

#### Etapa 6: troque o código por um refresh token

Execute este comando curl no terminal, com os seus valores no lugar dos marcadores:

```bash
curl -X POST https://oauth2.googleapis.com/token \
  -d "code=YOUR_AUTHORIZATION_CODE" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "redirect_uri=http://localhost" \
  -d "grant_type=authorization_code"
```

Resposta de sucesso:

```json
{
  "access_token": "ya29.a0AfH6SMBx...",
  "expires_in": 3599,
  "refresh_token": "1//0eHusbKw...",
  "scope": "https://mail.google.com/",
  "token_type": "Bearer"
}
```

> [!WARNING]
>
> **Guarde o seu `refresh_token` agora.** O Google só o retorna na primeira autorização. Se você perdê-lo, terá de revogar o acesso e autorizar de novo.

#### Etapa 7: configure no Notifuse

| Campo                            | Valor                        |
| -------------------------------- | ---------------------------- |
| **Host**                         | `smtp.gmail.com`             |
| **Porta**                        | `587`                        |
| **Usar TLS**                     | `On`                         |
| **Método**                       | **OAuth2**                   |
| **Provedor OAuth2**              | **Google Workspace / Gmail** |
| **Endereço da caixa de correio** | O seu endereço do Gmail      |
| **Client ID**                    | O Client ID da etapa 4       |
| **Client secret**                | O Client Secret da etapa 4   |
| **Token de atualização**         | O refresh token da etapa 6   |

#### Validade do refresh token

Com um **app publicado**, o refresh token continua válido indefinidamente, a não ser que:

| Condição                                                                                                          | Resultado                                      |
| ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| O token fique sem uso por **6 meses**                                                                             | O token expira                                 |
| Você mude a sua **senha do Google**                                                                               | O token é revogado                             |
| Você ultrapasse **50 refresh tokens** por cliente                                                                 | O token mais antigo é revogado automaticamente |
| Você revogue o acesso manualmente em [myaccount.google.com/permissions](https://myaccount.google.com/permissions) | O token é revogado                             |

> [!NOTE]
>
> Se o seu token deixar de ser válido, repita as etapas 5 e 6 para gerar um novo refresh token.

---

## Lista de remetentes

Adicione os endereços de remetente que esta integração SMTP pode usar:

| Campo     | Descrição                      | Exemplo                  |
| --------- | ------------------------------ | ------------------------ |
| **Nome**  | Nome de exibição do remetente  | `Support Team`           |
| **Email** | Endereço de email do remetente | `support@yourdomain.com` |

Clique em **Adicionar remetente** para adicionar vários endereços de remetente.

---

## Tipos de uso

Escolha o que esta integração SMTP envia no menu **⋯** do card dela em **Configurações** → **Integrações** (**Usar para marketing**, **Usar para transacional**), ou no painel **Envio de emails** dessa página:

| Opção                      | Descrição                                                   |
| -------------------------- | ----------------------------------------------------------- |
| **Usar para transacional** | Redefinições de senha, confirmações de pedido, notificações |
| **Usar para marketing**    | Newsletters, campanhas promocionais, anúncios               |

Escolha as duas opções para enviar todos os tipos de email pela mesma configuração SMTP.

---

## Limitações

O SMTP não tem webhooks, então o Notifuse não recebe de uma integração SMTP atualizações de status de entrega, notificações de retorno nem reclamações de spam ou abuso.

> [!NOTE]
>
> O Notifuse adiciona **rastreamento de aberturas e cliques** a todos os emails, qualquer que seja o provedor de email.

Para ter webhooks de entrega e os outros recursos de provedor, use um provedor de serviço de email como [Mailgun](https://www.notifuse.com/pt/docs/integrations/mailgun.md), [Postmark](https://www.notifuse.com/pt/docs/integrations/postmark.md) ou [SparkPost](https://www.notifuse.com/pt/docs/integrations/sparkpost.md).

---

## Servidores SMTP comuns

| Provedor      | Host                              | Porta | TLS | Tipo de autenticação |
| ------------- | --------------------------------- | ----- | --- | -------------------- |
| Gmail         | `smtp.gmail.com`                  | `587` | Sim | OAuth2 (obrigatório) |
| Microsoft 365 | `smtp.office365.com`              | `587` | Sim | OAuth2 (obrigatório) |
| Amazon SES    | `email-smtp.region.amazonaws.com` | `587` | Sim | Basic Auth           |
| SendGrid      | `smtp.sendgrid.net`               | `587` | Sim | Basic Auth           |
| Mailgun       | `smtp.mailgun.org`                | `587` | Sim | Basic Auth           |

> [!NOTE]
>
> O Gmail e o Microsoft 365 descontinuaram a autenticação básica: use OAuth2 com eles.

---

## Solução de problemas

### Microsoft 365: "535 5.7.3 Authentication unsuccessful"

Esse erro geralmente significa:

1. A entidade de serviço não foi registrada no Exchange Online (etapa 4)
2. As permissões da caixa de correio não foram concedidas (etapa 5)
3. O **Endereço da caixa de correio** não corresponde à caixa de correio autorizada

### Gmail: "unauthorized_client"

Esse erro significa:

1. O refresh token foi gerado com outro Client ID ou Client Secret
2. Gere o refresh token de novo com as suas credenciais atuais

### Gmail: "invalid_grant"

Esse erro significa:

1. O refresh token expirou (7 dias no modo Testing)
2. O usuário mudou a senha do Google
3. O token foi revogado ou ultrapassou o limite de 50 tokens

**Solução**: gere um novo refresh token seguindo as etapas 5 e 6.

---

## Testes

Clique em **Enviar um e-mail de teste** no topo do formulário da integração, ou em **Enviar teste** no card dela, para verificar a sua configuração.
