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

# Envio de email

> Envie mensagens, trate a aceitação e resultados parciais em lote e acompanhe a entrega.

Use uma [identidade verificada](/pt/email/identities) na região de destino. O endereço `from` deve pertencer a esse domínio ou a um de seus subdomínios. Enviar exige `email:SendMessage` na identidade; envios com template também exigem `email:SendTemplatedMessage` no template.

<span id="send-a-message" />

## Enviar uma mensagem

<Tabs>
  <Tab title="Console">
    Abra Email e **Sent messages** para enviar uma mensagem e consultar seu estado. Selecione uma identidade verificada e informe remetente, destinatários, assunto e corpo.
  </Tab>

  <Tab title="API">
    Envie `POST /v1/sent-messages`. Use o cabeçalho `Idempotency-Key` ao repetir a mesma solicitação para que um timeout de rede não produza outro email.

    ```json theme={null}
    {
      "identity":"example.com",
      "from":"updates@example.com",
      "to":["reader@example.net"],
      "subject":"Your report is ready",
      "content":{"text":"Your report is ready to view."},
      "configuration_set":"transactional"
    }
    ```

    `configuration_set` é opcional. Seletores de recursos aceitam um UUID, um nome no escopo da conta ou um CRN correspondente. Consulte [Autenticação](/pt/authentication) para o token bearer e o cabeçalho `X-Account-Id`.
  </Tab>

  <Tab title="CLI">
    Salve a solicitação JSON da aba API como `request-1.json`. Use sua conta e região configuradas.

    ```bash theme={null}
    basaltic email sent-message send --from-file request-1.json
    ```
  </Tab>

  <Tab title="Go">
    Salve a solicitação JSON da aba API como `request-1.json`. Configure credenciais, conta e região pelas variáveis de ambiente do SDK.

    ```go theme={null}
    package main

    import (
    	"context"
    	"encoding/json"
    	"fmt"
    	"os"

    	basaltic "github.com/basaltic-sh/sdk-go"
    	"github.com/basaltic-sh/sdk-go/email"
    )

    func readJSON(path string, value any) error {
    	data, err := os.ReadFile(path)
    	if err != nil {
    		return err
    	}
    	return json.Unmarshal(data, value)
    }

    func run() error {
    	ctx := context.Background()
    	cfg, err := basaltic.NewConfig(ctx)
    	if err != nil {
    		return err
    	}
    	client := email.New(cfg)
    	var request1 email.SendMessageRequest
    	if err := readJSON("request-1.json", &request1); err != nil {
    		return err
    	}
    	result1, err := client.SendMessage(ctx, &request1)
    	if err != nil {
    		return err
    	}
    	fmt.Printf("%+v\n", result1)
    	return nil
    }

    func main() {
    	if err := run(); err != nil {
    		fmt.Fprintln(os.Stderr, err)
    		os.Exit(1)
    	}
    }
    ```
  </Tab>
</Tabs>

`content` seleciona um modo explícito: `text` e/ou `html`, `raw` para uma mensagem RFC 5322 completa ou `template` com `template_data`. Texto nunca é inferido como HTML. Informe `subject` para texto/HTML; mensagens brutas e templates fornecem seu próprio assunto. O serviço valida o remetente e assina emails enviados com DKIM. Para conteúdo reutilizável, consulte [Templates e envios em lote](/pt/email/templates).

<span id="acceptance-and-delivery" />

## Aceitação e entrega

A resposta contém um `message` com UUID, CRN e ResourceRef `identity`. A aceitação bem-sucedida da API enfileira a mensagem. Ela não comprova entrega na caixa de entrada.

| Estado | Significado |
| - | - |
| `queued` | Aceita e aguardando um worker de envio. |
| `sending` | Uma tentativa de entrega SMTP está em andamento. |
| `sent` | O servidor SMTP destinatário aceitou a mensagem. |
| `failed` | A tentativa SMTP ou o processo de envio falhou. |
| `bounced` | Um retorno de falha foi informado depois. |
| `complained` | Uma reclamação foi informada depois. |

Leia `GET /v1/sent-messages/{message_id}` para obter `smtp_response`, `error_message` e os horários dos resultados. Um registro de mensagem pode conter vários destinatários; seu estado não é um recibo individual de entrega para cada endereço. Envie mensagens separadas quando precisar de um resultado independente por destinatário.

Liste mensagens com `GET /v1/sent-messages`, filtrando opcionalmente por `identity`, `status` ou `recipient`. Use `meta.marker` para a próxima página, mantendo os filtros. Leia texto/HTML decodificados completos em `/v1/sent-messages/{message_id}/content`, baixe MIME reconstruído em `/raw` e arquivos individuais em `/attachments/{attachment_id}`. A leitura de conteúdo exige `email:GetSentMessageContent`, separadamente do acesso a metadados.

<span id="suppressions-and-rejections" />

## Supressões e rejeições

Supressões da conta removem destinatários correspondentes antes de enfileirar. A solicitação falha quando todos os destinatários são suprimidos. Um conjunto de configuração pode ignorar explicitamente endereços suprimidos selecionados; use isso somente após resolver a causa. Crie entradas manuais com `POST /v1/suppressions`; endereços duplicados retornam 409. Use `PATCH /v1/suppressions/{suppression_id}` para alterar descrição ou expiração. A omissão preserva a expiração e null a torna permanente. Leia e exclua supressões individuais por UUID no mesmo caminho.

Entradas manuais e criadas por retornos de falha ou reclamações aparecem em **Suppressions**. Remover uma entrada permite novos envios; não reenvia emails.

Solicitações rejeitadas não criam registros de mensagens enfileiradas. Consulte `GET /v1/rejections` para o motivo da rejeição, destinatários afetados e referência opcional da identidade. Uma rejeição pode não ter identidade quando ela não pôde ser resolvida.

Para tendências agregadas de envio e feedback, use [Métricas de Email](/pt/email/metrics). Detalhes de aberturas e cliques por mensagem continuam disponíveis em `GET /v1/sent-messages/{message_id}/engagement`.

<span id="message-retention-and-attachments" />

## Retenção de mensagens e anexos

O conteúdo de mensagens enviadas é mantido por **30 dias**, incluídos no preço de envio. A resposta inclui `expires_at`. O histórico fica indisponível após a expiração; objetos de anexos continuam sujeitos ao ciclo de vida do bucket e às cobranças de Storage.

Para anexar objetos existentes, informe `attachments` ao enviar uma mensagem:

```json theme={null}
{
  "identity": "example.com",
  "from": "sender@example.com",
  "to": ["recipient@example.net"],
  "subject": "Your report",
  "content": {"text": "Your report is attached."},
  "attachments": [
    {"bucket":"email-files","key":"reports/report.pdf","name":"report.pdf"}
  ]
}
```

O bucket deve pertencer à mesma conta e região. `storage:GetObject` é necessário. Um `version_id` opcional seleciona uma versão específica do objeto; o serviço fixa a versão e o checksum selecionados para que uma sobrescrita posterior não altere silenciosamente um email aceito. Um anexo ausente ou alterado impede a entrega.

Quando `content.raw` contém uma mensagem MIME completa com anexos binários, informe também `attachments_bucket`, usando nome, UUID ou CRN do bucket. Email extrai esses anexos para `email/{identity_id}/sent/{message_id}/` e mantém somente suas referências junto ao corpo da mensagem. Esse caminho exige `storage:PutObject` e `storage:GetObject` nesse prefixo. Os anexos são lidos antes da assinatura DKIM.

Cotas da organização limitam o tamanho codificado completo, destinatários de envio aceitos por segundo móvel e em 24 horas móveis. Elas se aplicam entre contas e identidades na região e contam os destinatários restantes após a filtragem de supressões. Admissões com falha não consomem cota. Consulte a [referência de cotas e retenção](/pt/email/receiving#quotas-and-retention).


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