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

# Enviar um e-mail

> Envie e-mails em HTML ou texto simples e acompanhe a entrega para cada destinatário.

## O que é

A API de e-mail envia um e-mail para um ou mais destinatários. Use-a para
notificações transacionais, atualizações de conta, recibos e mensagens
personalizadas.

## Antes de começar

* Armazene sua chave de API da YCloud em `YCLOUD_API_KEY`.
* Registre e ative o domínio remetente na sua conta YCloud.
* Use um endereço de remetente do domínio ativado.
* Prepare conteúdo em HTML ou texto simples com no máximo 150 KB.

## Como funciona

Envie o e-mail com `POST /emails`. A resposta confirma que a YCloud aceitou
o e-mail e retorna seu `id`. A entrega ocorre separadamente para cada endereço em
`to`, `cc` e `bcc`.

Inscreva-se em `email.delivery.updated` para receber estados por destinatário como
`sent`, `delivered`, `undelivered` e `failed`.

## Requisição

`POST /emails`

### Campos da requisição

| Campo | Obrigatório | Descrição |
| - | - | - |
| `from` | Sim | Endereço do remetente em um domínio ativado. Um nome de exibição é opcional. |
| `to` | Sim | Um ou mais endereços de destinatário separados por vírgula. Máximo de 100 endereços. |
| `subject` | Sim | Linha de assunto. Máximo de 255 caracteres. |
| `content` | Sim | Corpo em HTML ou texto simples. Tamanho máximo de 150 KB. |
| `contentType` | Não | `text/html` ou `text/plain`. Os padrões e o comportamento de rastreamento dependem do tipo de conteúdo. |
| `cc` | Não | Destinatários em cópia separados por vírgula. |
| `bcc` | Não | Destinatários em cópia oculta separados por vírgula. |
| `replyTo` | Não | Endereço usado quando um destinatário responde. |
| `summary` | Não | Resumo curto do e-mail. Máximo de 70 caracteres. |
| `variables` | Não | Um objeto de personalização para cada endereço em `to`. |
| `externalId` | Não | Sua referência única para reconciliar o e-mail com um registro interno. |
| `callbackUrl` | Não | URL de relatório de entrega por mensagem. Use endpoints de webhook para novas integrações. |

### Exemplo de requisição

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --request POST https://api.ycloud.com/v2/emails \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "from": "Support Team<support@example.com>",
    "to": "customer@example.com",
    "subject": "Welcome",
    "contentType": "text/html",
    "content": "<h1>Welcome</h1><p>Thanks for joining us.</p>",
    "externalId": "welcome-10001"
  }'
```

## Resposta

Uma resposta bem-sucedida retorna o objeto de e-mail criado. A aceitação não
significa que todos os destinatários receberam o e-mail.

### Exemplo de resposta

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "EMAIL_ID",
  "from": {
    "address": "support@example.com",
    "name": "Support Team"
  },
  "to": [
    {
      "address": "customer@example.com"
    }
  ],
  "subject": "Welcome",
  "contentType": "text/html",
  "externalId": "welcome-10001",
  "totalRecipients": 1,
  "createTime": "2026-07-16T12:00:00.000Z"
}
```

### Campos da resposta

| Campo | Descrição |
| - | - |
| `id` | ID do e-mail na YCloud. Armazene-o para correlacionar eventos de entrega por destinatário. |
| `from` | Caixa de correio do remetente analisada. |
| `to`, `cc`, `bcc` | Caixas de correio dos destinatários analisadas. |
| `contentType` | Tipo MIME usado no corpo do e-mail. |
| `totalRecipients` | Total de destinatários em `to`, `cc` e `bcc`. |
| `totalPrice` | Preço total do e-mail quando disponível. |
| `currency` | Moeda do preço no padrão ISO 4217. |
| `createTime` | Horário de criação do e-mail no formato RFC 3339. |
| `externalId` | A referência fornecida na requisição. |

## Personalizar o conteúdo

Coloque as variáveis entre caracteres `#` no conteúdo. Forneça um objeto de variáveis
para cada endereço em `to`.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "to": "alice@example.com,bob@example.com",
  "content": "Hello #name#!",
  "variables": [
    { "name": "Alice" },
    { "name": "Bob" }
  ]
}
```

## Status de entrega

Inscreva-se em `email.delivery.updated`. Cada evento identifica o e-mail e o
`recipientAddress` específico, porque os destinatários podem ter estados finais
diferentes.

Mensagens `text/plain` não geram eventos de rastreamento de cliques ou aberturas.

## Limites e solução de problemas

* O domínio remetente deve estar ativado antes do envio.
* `to` suporta no máximo 100 endereços.
* `subject` suporta no máximo 255 caracteres.
* `content` suporta no máximo 150 KB.
* Uma resposta bem-sucedida da API ainda pode ser seguida por um evento
  `undelivered` ou `failed` de um destinatário.
* Use o `id` do e-mail, o endereço do destinatário e `externalId` ao investigar a
  entrega.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.