> ## 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.

# Visão geral de mensagens

> Envio transacional de e-mail e SMS via API: pré-requisitos, cobrança, remetentes e templates — pela API de mensageria da gu1 para comunicações com clientes.

## O que os endpoints fazem

Enviam **e-mail** e **SMS** transacionais a partir do seu backend, **fora** dos [Workflows](/pt/workflows/overview). Cada envio bem-sucedido é cobrado como no marketplace: **pacote de execuções** ou **saldo de tokens**.

São rotas HTTP dedicadas em `/marketplace/messaging/`, não substituem ações de fluxo como “Enviar notificação”.

## URL base

```
POST https://api.gu1.ai/marketplace/messaging/send-email
POST https://api.gu1.ai/marketplace/messaging/send-sms
```

## Autenticação

Igual ao restante da API gu1. Ver [Autenticação](/pt/api-reference/authentication).

```bash theme={null}
Authorization: Bearer SUA_API_KEY
Content-Type: application/json
```

Para utilizadores com várias organizações (sessão no painel):

```http theme={null}
X-Organization-ID: <uuid>
```

## Integrações no marketplace

| Canal  | Código (referência)   |
| ------ | --------------------- |
| E-mail | `global_sender_email` |
| SMS    | `global_sender_sms`   |

Sem integração ativa ou sem `MS_PROVIDER_URL` configurado no servidor, a API retorna erro (**`400`** ou de configuração).

## Cobrança

Antes do envio, se o preço for > 0, verifica-se **execução no pack** ou **saldo em tokens**. Caso contrário, **`400`**. As mensagens de erro destes endpoints estão em **inglês** no campo `error`.

## E-mail: domínios e remetentes

1. Adicionar e **verificar** domínio em **Configurações → E-mail → Domínios**.
2. Opcional: criar **remetente** em **Configurações → E-mail → Remetentes** para nome de exibição ou reutilizar UUID.

Na API: **`fromEmail`** (endereço completo; domínio **verificado** na org) ou **`fromSenderId`** (UUID) — não os dois. Domínio não registrado ou sem verificação DNS → **`400`** com `success: false` (detalhes em [Enviar e-mail](/pt/api-reference/messaging/send-email#remetente-personalizado-fromemail)).

Sem `fromEmail` nem `fromSenderId`, usa-se o **remetente padrão da plataforma Gu1** (comportamento esperado).

## Conteúdo

* **Template:** `templateId` + `templateParams` opcional (sem corpo inline).
* **Inline:** `htmlBody`/`textBody` (e-mail) ou `body` (SMS); `templateParams` substitui `{{variáveis}}` também no **subject** (e-mail).
* **E-mail inline:** `subject` obrigatório; pelo menos um de `htmlBody` ou `textBody`.

IDs de template: **Configurações da organização → Applications → Templates de mensagens** (copiar ID).

## Resposta

`{ "success": true, "messageId": "..." }` ou `{ "success": false, "error": "..." }`.

## Próximos passos

<CardGroup cols={2}>
  <Card title="Enviar e-mail" icon="envelope" href="/pt/api-reference/messaging/send-email">
    `POST .../send-email`
  </Card>

  <Card title="Enviar SMS" icon="message" href="/pt/api-reference/messaging/send-sms">
    `POST .../send-sms`
  </Card>
</CardGroup>