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

# Enviar e-mail

> POST /marketplace/messaging/send-email — e-mail transacional com template ou HTML inline — pela API de mensageria da gu1 para comunicações com clientes.

Requer integração **Email** ativa no marketplace. Visão geral em [Mensagens — visão geral](/pt/api-reference/messaging/overview).

## Endpoint

```http theme={null}
POST https://api.gu1.ai/marketplace/messaging/send-email
```

## Cabeçalhos

```http theme={null}
Authorization: Bearer SUA_API_KEY
Content-Type: application/json
X-Organization-ID: <uuid>   # opcional
```

## Corpo

<ParamField body="to" type="string" required>
  E-mail do destinatário.
</ParamField>

<ParamField body="fromEmail" type="string">
  Endereço completo (ex.: `noreply@meu-dominio.com`). O **domínio** deve estar registrado e **verificado** na organização (**Configurações → E-mail → Domínios**). Não é obrigatório cadastrar esse endereço em Remetentes se o domínio já estiver verificado. Exclusivo com `fromSenderId`.
</ParamField>

<ParamField body="fromSenderId" type="string (UUID)">
  UUID do remetente. Exclusivo com `fromEmail`.
</ParamField>

Se **omitir** `fromEmail` e `fromSenderId`, a API usa o **remetente padrão da plataforma Gu1**. Comportamento esperado, não é erro.

## Remetente personalizado (`fromEmail`)

Se enviar `fromEmail`, por exemplo `example@meu-dominio.com`, a API valida o domínio (`meu-dominio.com`) **antes** do envio. A resposta é **`400`** com `{ "success": false, "error": "<mensagem em inglês>" }`; **o e-mail não é enviado** até o domínio estar verificado.

| Situação                                        | Resposta da API                                                                                                                                         |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Domínio **nunca adicionado** na Gu1 para a org  | `Domain "meu-dominio.com" is not registered in Gu1. Add and verify it under Settings → Email → Domains before using sender "example@meu-dominio.com".`  |
| Domínio na Gu1 mas **DNS ainda não verificado** | `Domain "meu-dominio.com" is not verified yet. Complete DNS records and click Verify under Settings → Email → Domains.`                                 |
| Domínio **verificado**                          | A requisição segue; qualquer local-part nesse domínio é aceito sem linha em Remetentes. Se o endereço existir em Remetentes, usa-se o nome configurado. |

Exemplo de rejeição (domínio não verificado):

```json theme={null}
{
  "success": false,
  "error": "Domain \"meu-dominio.com\" is not verified yet. Complete DNS records and click Verify under Settings → Email → Domains."
}
```

<ParamField body="templateParams" type="object">
  Mapa para `{{placeholders}}`. Padrão `{}`.
</ParamField>

**Modo template:** `templateId` (canal email). Sem `htmlBody`/`textBody`. `subject` opcional como fallback.

**Modo inline:** `subject` obrigatório; `htmlBody` e/ou `textBody`. Sem `templateId`.

## Exemplo (inline + variáveis)

```json theme={null}
{
  "to": "user@example.com",
  "subject": "Seu código: {{token}}",
  "htmlBody": "<p>Código: <strong>{{token}}</strong></p>",
  "templateParams": { "token": "482910" }
}
```

## Erros e HTTP

Na maioria dos casos: `{ "success": false, "error": "<mensagem em inglês>" }`. Corpos inválidos podem retornar outro formato (ex.: Zod) com **400**. Mensagens de negócio em **`error` são em inglês.**

| Situação                                     | HTTP    | Exemplo de `error`                                                                                                         |
| -------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| Integração Email inativa                     | **400** | `Email integration is not active. Enable Email (global_sender_email) in Applications (Marketplace) for this organization.` |
| `MS_PROVIDER_URL` não configurado            | **400** | `MS_PROVIDER_URL is not configured on the server. Configure the messaging provider to send email.`                         |
| Custo > 0 sem saldo/pack                     | **400** | `Insufficient balance for this send (cost … credits). …`                                                                   |
| Envio OK, falha ao cobrar                    | **400** | `Insufficient balance to record billing for this send. …`                                                                  |
| `templateId` + corpo inline                  | **400** | `Use either templateId + templateParams, or htmlBody/textBody only — not both.`                                            |
| Sem template nem corpo                       | **400** | `Provide templateId or htmlBody/textBody.`                                                                                 |
| Inline sem `subject`                         | **400** | `subject is required when not using a template.`                                                                           |
| Template inexistente / outra org             | **404** | `Template not found or not accessible for this organization.`                                                              |
| Canal do template ≠ email                    | **400** | `Template channel is "<channel>"; email is required.`                                                                      |
| Assunto vazio após variáveis                 | **400** | `The template has no subject or it is empty after replacing variables. …`                                                  |
| `fromSenderId` e `fromEmail`                 | **400** | `Send only one of fromSenderId or fromEmail, not both.`                                                                    |
| `fromSenderId` inválido                      | **400** | `fromSenderId does not match a sender for this organization. …`                                                            |
| Domínio do `fromEmail` não registrado na org | **400** | `Domain "…" is not registered in Gu1. Add and verify it under Settings → Email → Domains before using sender "…".`         |
| Domínio registrado mas DNS não verificado    | **400** | `Domain "…" is not verified yet. Complete DNS records and click Verify under Settings → Email → Domains.`                  |
| Assunto vazio após `{{…}}`                   | **400** | `Subject is empty after replacing variables.`                                                                              |
| Corpo vazio após render                      | **400** | `htmlBody or textBody is empty after rendering.`                                                                           |
| Sem org na sessão                            | **401** | `{ "error": "Organization ID not found" }`                                                                                 |

Sempre verifique `success` e `error`; o provedor pode responder falha com **200** e `success: false`.