API atual/Referência completa/E-mail: envio, layout e logs

POSTEnviar e-mail

Envia uma mensagem avulsa a um destinatário, com corpo livre ou a partir de um modelo da loja.

Use esta operação para disparar um e-mail que não nasce de um evento da loja: um aviso manual a um cliente, um teste de configuração do SMTP, uma comunicação pontual de um sistema externo. A mensagem sai pelo provedor de e-mail configurado da loja, com o remetente padrão (ou o que você informar em from), e fica registrada no log de entrega.

A chamada é síncrona: o servidor conversa com o provedor e só responde depois. A resposta traz o nome do provedor e uma transcrição curta do diálogo (log), útil para entender por que uma mensagem "enviada com sucesso" pode não ter saído de fato.

POST/api/v1/admin/emailAdmin

Enviar um e-mail avulso

Exige token de administrador com o privilégio manage_email ou manage_settings.

Corpo da requisição

tostringobrigatório

Endereço do destinatário. Um único endereço por chamada.

subjectstringobrigatório

Assunto. Quando você informa template_name e o modelo salvo na loja tem assunto próprio, o assunto do modelo vence o seu.

bodystring

Corpo da mensagem em HTML. Ignorado quando template_name e template_data são enviados juntos e o modelo existe.

template_namestring

Código de um modelo de e-mail da loja (por exemplo order_status_processing). Só tem efeito junto com template_data.

template_dataobject

Valores usados para preencher os marcadores do modelo. Chaves livres, de acordo com o modelo escolhido.

reply_tostring

Endereço para respostas.

fromstring

Endereço do remetente só desta mensagem. Vazio mantém o remetente configurado da loja.

from_namestring

Nome de exibição do remetente, só desta mensagem.

user_iduuid

Id do usuário destinatário, quando existe. Liga a mensagem à caixa de notificações dele e escolhe o idioma preferido dele quando language não é informado.

languagestringpadrão: pt-BR

Idioma do modelo (pt-BR, en).

recipient_typestringpadrão: customer

customervendoradminall

Qual variante do modelo usar: o cliente recebe a versão completa, o administrador uma versão enxuta, o seller os detalhes do sub-pedido.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/email" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "maria.souza@example.com",
    "subject": "Teste de envio",
    "body": "<p>Olá, este é um teste.</p>"
  }'

Resposta

200Mensagem entregue ao provedor

json

{
  "message": "email sent",
  "provider": "smtp",
  "log": ["connected to smtp.example.com:587", "STARTTLS ok", "250 queued"]
}

Campos da resposta

messagestring

Sempre email sent em sucesso.

providerstring

Provedor que atendeu o envio. smtp envia de verdade; console só escreve a mensagem no log do servidor (ambientes de teste).

logarray

Linhas de texto com o diálogo com o provedor. O conteúdo varia por provedor.

Erros

Status	Quando	Corpo de exemplo
400	Corpo não é JSON válido.	`{"error":"invalid request body","detail":"..."}`
400	`to` vazio.	`{"error":"to is required"}`
400	`subject` vazio.	`{"error":"subject is required"}`
401	Sem token ou token expirado.	`{"error":"invalid or expired token"}`
403	O usuário não tem o privilégio de e-mail.	`{"error":"insufficient privileges","privilege_required_any":["manage_email","manage_settings"]}`
500	O provedor recusou ou a conexão falhou. O corpo traz `provider` e `log` para diagnóstico.	`{"error":"failed to send email","message":"...","detail":"...","provider":"smtp","log":["..."]}`

Veja também