Envio de email

Use uma identidade verificada 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.

Enviar uma mensagem

Console
API
CLI
Go

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.

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.

{
  "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 para o token bearer e o cabeçalho X-Account-Id.

Salve a solicitação JSON da aba API como request-1.json. Use sua conta e região configuradas.

basaltic email sent-message send --from-file request-1.json

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.

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)
	}
}

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.

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.

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. Detalhes de aberturas e cliques por mensagem continuam disponíveis em GET /v1/sent-messages/{message_id}/engagement.

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:

{
  "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.

Primeiros passos

Produtos

Plataforma

Ajuda

Enviar uma mensagem

Aceitação e entrega

Supressões e rejeições

Retenção de mensagens e anexos

​Enviar uma mensagem

​Aceitação e entrega

​Supressões e rejeições

​Retenção de mensagens e anexos

Enviar uma mensagem

Aceitação e entrega

Supressões e rejeições

Retenção de mensagens e anexos