Recebimento de email

Configure o recebimento em uma identidade de domínio verificada. A configuração de recebimento contém apenas enabled e attachments_bucket. O campo dns_records da identidade contém orientações DNS de envio e recebimento, incluindo o valor MX completo. Todas as identidades usam as mesmas verificações de propriedade e IAM.

Habilitar o recebimento e adicionar uma regra

Console
API
CLI
Go

Abra Email → Identities e selecione o domínio.

Em Settings, escolha um Attachments bucket no card Receiving, ative o interruptor e selecione Save. O bucket deve pertencer à mesma conta e região.
Abra Recipient rules e selecione Create rule. Escolha um endereço exato, prefixo de endereço ou todos os endereços e selecione um tópico de Notifications da mesma conta e região no seletor de recursos.
Abra DNS records e publique o registro MX de Receiving records. Sending records contém os registros usados para verificação e envio, incluindo os de MAIL FROM personalizado. A tabela de regras de destinatário mostra cada tópico de destino pelo nome. Selecione uma regra para acessar os controles de exclusão ou use sua ação de habilitar/desabilitar. A retenção de mensagens e o bucket de anexos selecionado aparecem nos detalhes da identidade acima das abas. Cotas da organização controlam o tamanho das mensagens e o tráfego.

Envie PATCH /v1/identities/{identity_id}/receiving:

{"enabled":true,"attachments_bucket":"incoming-email-files"}

Envie POST /v1/identities/{identity_id}/recipient-rules:

{"match_type":"exact","local_part":"support","topic":"incoming-mail","enabled":true}

Isso encaminha support@example.com quando a identidade é example.com. Depois de configurar a regra, publique o registro MX em dns_records da identidade com group: "receiving".

Salve as solicitações JSON da aba API, em ordem, como request-1.json, request-2.json. Defina IDENTITY_ID como o UUID do recurso. Use a conta e a região configuradas.

basaltic email identity update-receiving "$IDENTITY_ID" --from-file request-1.json
basaltic email recipient-rule create "$IDENTITY_ID" --from-file request-2.json

Salve as solicitações JSON da aba API, em ordem, como request-1.json, request-2.json. Defina IDENTITY_ID como o UUID do recurso. 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.UpdateReceivingConfigurationRequest
	if err := readJSON("request-1.json", &request1); err != nil {
		return err
	}
	if err := client.UpdateReceivingConfiguration(ctx, os.Getenv("IDENTITY_ID"), &request1); err != nil {
		return err
	}
	var request2 email.CreateRecipientRuleRequest
	if err := readJSON("request-2.json", &request2); err != nil {
		return err
	}
	result2, err := client.CreateRecipientRule(ctx, os.Getenv("IDENTITY_ID"), &request2)
	if err != nil {
		return err
	}
	fmt.Printf("%+v\n", result2)
	return nil
}

func main() {
	if err := run(); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

Criar uma regra exige email:CreateRecipientRule na identidade e notifications:Publish no tópico de destino. Negações na política do tópico também se aplicam. Selecionar um bucket delega storage:PutObject e storage:GetObject no prefixo email/{identity_id}/ desse bucket. Permissões IAM atuais, limites de permissões, políticas do bucket e restrições da sessão original continuam sendo aplicados. Consulte Permissões.

Correspondência de destinatários

match_type define explicitamente o comportamento da correspondência:

Modo	`local_part`	Correspondência
`exact`	`support`	Apenas `support@example.com`.
`prefix`	`reply+`	Endereços que começam com `reply+`.
`all`	Omitido ou vazio	Qualquer endereço nesta identidade.

Regras exatas têm prioridade, seguidas pelo prefixo correspondente mais longo e depois pela regra geral. Somente regras habilitadas aceitam destinatários. Um destinatário sem correspondência é rejeitado durante a entrega SMTP. Você pode configurar até 100 regras por identidade. Regras têm UUID e CRN próprios. POST cria uma regra e retorna 409 quando seu padrão de correspondência já existe. Leia ou exclua uma regra em /v1/identities/{identity_id}/recipient-rules/{rule_id}. Use PATCH nesse caminho para alterar somente os campos informados. Respostas de listagem incluem a paginação normal em meta. O campo topic da resposta é um ResourceRef com UUID, CRN e nome. O PATCH de configuração também preserva omissões. Enviar attachments_bucket: null limpa o vínculo somente quando o recebimento está desabilitado. Para desabilitar e desvincular juntos, inclua enabled: false e attachments_bucket: null na mesma solicitação.

Ler emails aceitos

GET /v1/received-messages lista metadados de toda a conta, com filtros opcionais identity, recipient e review_reason. Leia um registro pelo UUID e solicite /content, /raw ou /attachments/{attachment_id} separadamente. /content retorna texto e HTML decodificados completos; /raw baixa o MIME reconstruído. IDs de anexos são UUIDs opacos estáveis. Metadados e conteúdo exigem permissões separadas. Trate HTML como dados não confiáveis e sanitize antes de renderizar. identity é um ResourceRef. rfc_message_id no conteúdo é o cabeçalho RFC Message-ID, não o UUID do recurso Email. notification_status é pending, retrying ou published; notification_error fornece detalhes seguros da falha. A publicação tenta novamente automaticamente até a expiração. Esses campos descrevem o evento de notificação, não a aceitação SMTP, que ocorreu antes de a mensagem ser retornada. review_reason pode ser clear, malware, spam ou sender_unverified. Conteúdo com malware fica em quarentena e não pode ser baixado pela API de conteúdo. Verifique content_available e expires_at antes de tentar recuperar. published_at informa quando o evento de Notifications foi publicado, não quando todos os assinantes terminaram de processá-lo. Os campos message_id, in_reply_to e references do conteúdo analisado são cabeçalhos RFC de email. Eles não são UUIDs de recursos Basaltic nem ResourceRefs.

Armazenamento de anexos

Cada anexo aceito é armazenado como um objeto separado no bucket selecionado. Seus metadados contêm um ResourceRef bucket, key, version_id opcional e sha256. Preços, cotas, criptografia e regras de ciclo de vida de Storage se aplicam normalmente. Não há franquia adicional de armazenamento de Email nem limite acumulado de armazenamento de anexos. Um objeto ausente, alterado ou excluído fica indisponível para download. Email confirma uma entrega SMTP recebida somente depois que os anexos e o registro da mensagem estão persistidos. Falhas de armazenamento retornam uma falha SMTP temporária para que o remetente tente novamente. Tentativas repetidas não cobram uma segunda entrega recebida. Anexos com malware nunca são gravados no bucket do cliente. Alterar o bucket afeta novas mensagens; não move objetos existentes. Desabilitar o recebimento preserva o bucket selecionado e emails já aceitos. Limpar attachments_bucket com null exige que o recebimento esteja desabilitado.

Cotas e retenção

O conteúdo das mensagens enviadas e recebidas é mantido por 30 dias, incluídos no preço de envio ou recebimento. expires_at identifica o prazo. Mensagens expiradas ficam indisponíveis nas APIs mesmo se a publicação da notificação falhou. A limpeza em segundo plano remove o conteúdo retido; registros operacionais de cobrança e deduplicação podem permanecer. Objetos de anexos não são excluídos quando um email expira: o dono do bucket controla seu ciclo de vida e paga pelo armazenamento. Cotas da organização se aplicam entre contas e identidades em cada região:

Cota	Padrão	Significado
`email/message_size_bytes`	10 MiB	Email codificado completo, incluindo anexos; configurável até o teto de 50 MiB do serviço.
`email/received_recipients_per_second`	100	Entregas aceitas a destinatários em uma janela móvel de um segundo; tráfego excedente recebe falha SMTP temporária.
`email/sent_recipients_per_second`	28	Destinatários de envio aceitos em uma janela móvel de um segundo.
`email/sent_recipients_per_day`	Ilimitado	Destinatários de envio aceitos em 24 horas móveis; uma configuração da organização pode impor um limite.

Não há franquia diária de recebimento. Uma mensagem aceita para três destinatários conta como três entregas recebidas. Tentativas duplicadas são confirmadas sem nova contagem. SMTP rejeita mensagens acima da cota de tamanho da organização; falhas temporárias de capacidade ou dependências pedem que o remetente tente novamente. A correspondência de destinatários aceita 100 regras por domínio. A análise MIME tem limites técnicos de complexidade, separados da capacidade de armazenamento em bytes. A API de conteúdo retorna texto e HTML completos dentro da cota de tamanho de mensagens da organização. Recupere anexos do bucket ou pelo endpoint de download de anexos durante a retenção.

Primeiros passos

Produtos

Plataforma

Ajuda

Recebimento de email

Habilitar o recebimento e adicionar uma regra

Correspondência de destinatários

Ler emails aceitos

Armazenamento de anexos

Cotas e retenção

​Habilitar o recebimento e adicionar uma regra

​Correspondência de destinatários

​Ler emails aceitos

​Armazenamento de anexos

​Cotas e retenção

Habilitar o recebimento e adicionar uma regra

Correspondência de destinatários

Ler emails aceitos

Armazenamento de anexos

Cotas e retenção