VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Newsletter

Campanhas

Lista, consulta, cria, edita e apaga campanhas de e-mail em rascunho.

Listar campanhas

Devolve as campanhas, da mais nova para a mais antiga, inclusive as de sellers.

GET/api/v1/admin/newsletter/campaignsAdmin

Lista as campanhas de e-mail

Rota ligada ao módulo newsletter: com o módulo desligado a resposta é 403. Leitura exige view_newsletter, manage_newsletter ou manage_content.

Parâmetros de consulta

statusstring
RSAF
Filtra pelo estado, em letra: R rascunho, S enviando, A enviada, F falhou. As palavras draft e failed também funcionam; sent e sending viram A.
pageintegerpadrão: 1
Página, a partir de 1.
limitintegerpadrão: 20
Itens por página, 1 a 100; fora disso vale 20.
vendor_iduuid
Só campanhas desse seller.
marketplace_onlyboolean
Com true, 1 ou yes, só campanhas da loja.

Exemplo de requisição (Listar campanhas)

bash
curl "$BASE_URL/api/v1/admin/newsletter/campaigns?status=R" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar campanhas)

200Campanhas
json
{
  "items": [
    {
      "id": "b2247714-08c6-4ad9-b644-748eae7baa70",
      "subject": "Black Friday chegou",
      "html_body": "<h1>Ofertas</h1><p>Até 50% off.</p>",
      "text_body": "Ofertas: até 50% off.",
      "status": "R",
      "recipients": 0,
      "sent": 0,
      "failed": 0,
      "scheduled_at": "2026-11-27T12:00:00Z",
      "created_at": "2026-10-11T21:05:13.511196Z",
      "updated_at": "2026-10-11T21:05:13.511196Z"
    }
  ],
  "total": 26,
  "page": 1,
  "limit": 20
}

Campos da resposta

itemsarray

Campanhas da página.

iduuid
Identificador da campanha.
subjectstring
Assunto do e-mail.
html_bodystring
Corpo em HTML.
text_bodystring
Versão em texto puro.
statusstring
Letra do estado: R rascunho, S enviando, A enviada, F falhou.
recipientsinteger
Quantidade de inscritos ativos no momento do envio. 0 antes de enviar.
sentinteger
E-mails entregues ao provedor até agora.
failedinteger
E-mails que falharam até agora.
scheduled_atstring
Data informada para o envio. Apenas registro: não dispara nada sozinha.
sent_atstring
Quando o envio começou. Ausente em rascunho.
vendor_iduuid
Seller dono da campanha. Ausente em campanha da loja.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.
totalinteger
Total que atende ao filtro.
pageinteger
Página devolvida.
limitinteger
Itens por página usados.

Erros (Listar campanhas)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["view_newsletter","manage_newsletter","manage_content"]}
500Falha de banco.{"error":"failed to list campaigns","detail":"..."}

Consultar campanha

Devolve a campanha. Durante o envio, repita a chamada de tempos em tempos para acompanhar sent e failed.

GET/api/v1/admin/newsletter/campaigns/{id}Admin

Devolve uma campanha pelo id

Rota ligada ao módulo newsletter: com o módulo desligado a resposta é 403. Leitura exige view_newsletter, manage_newsletter ou manage_content.

Parâmetros de caminho

iduuidobrigatório
Identificador da campanha.

Exemplo de requisição (Consultar campanha)

bash
curl "$BASE_URL/api/v1/admin/newsletter/campaigns/b2247714-08c6-4ad9-b644-748eae7baa70" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Consultar campanha)

200Campanha
json
{
  "id": "b2247714-08c6-4ad9-b644-748eae7baa70",
  "subject": "Black Friday chegou",
  "html_body": "<h1>Ofertas</h1><p>Até 50% off.</p>",
  "text_body": "Ofertas: até 50% off.",
  "status": "R",
  "recipients": 0,
  "sent": 0,
  "failed": 0,
  "scheduled_at": "2026-11-27T12:00:00Z",
  "created_at": "2026-10-11T21:05:13.511196Z",
  "updated_at": "2026-10-11T21:05:13.511196Z"
}

Campos da resposta

iduuid
Identificador da campanha.
subjectstring
Assunto do e-mail.
html_bodystring
Corpo em HTML.
text_bodystring
Versão em texto puro.
statusstring
Letra do estado: R rascunho, S enviando, A enviada, F falhou.
recipientsinteger
Quantidade de inscritos ativos no momento do envio. 0 antes de enviar.
sentinteger
E-mails entregues ao provedor até agora.
failedinteger
E-mails que falharam até agora.
scheduled_atstring
Data informada para o envio. Apenas registro: não dispara nada sozinha.
sent_atstring
Quando o envio começou. Ausente em rascunho.
vendor_iduuid
Seller dono da campanha. Ausente em campanha da loja.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros (Consultar campanha)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["view_newsletter","manage_newsletter","manage_content"]}
404Não existe campanha com esse id.{"error":"campaign not found"}
500O id não é um UUID válido (500, não 404).{"detail":"o valor \"xx\" não é um uuid válido. Envie o identificador completo, com os 36 caracteres e os hífens. Corrija o campo e reenvie.","error":"failed to get campaign"}

Criar campanha

Cria a campanha sempre em rascunho (R). Nada é enviado até você chamar a rota de envio.

POST/api/v1/admin/newsletter/campaignsAdmin

Cria uma campanha em rascunho

Rota ligada ao módulo newsletter: com o módulo desligado a resposta é 403. Exige manage_newsletter ou manage_content.

Corpo da requisição

subjectstringobrigatório
Assunto do e-mail.
html_bodystring
Corpo em HTML. O envio acrescenta um rodapé "Cancelar inscrição" com link próprio de cada destinatário.
text_bodystring
Versão em texto puro. Usada quando não há HTML.
scheduled_atstring
Data prevista (RFC 3339). Fica só registrada: a plataforma não envia sozinha nessa data.

Exemplo de requisição (Criar campanha)

bash
curl -X POST "$BASE_URL/api/v1/admin/newsletter/campaigns" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "Black Friday chegou",
  "html_body": "<h1>Ofertas</h1><p>Até 50% off.</p>",
  "text_body": "Ofertas: até 50% off.",
  "scheduled_at": "2026-11-27T12:00:00Z"
}'

Resposta (Criar campanha)

201Campanha criada
json
{
  "id": "b2247714-08c6-4ad9-b644-748eae7baa70",
  "subject": "Black Friday chegou",
  "html_body": "<h1>Ofertas</h1><p>Até 50% off.</p>",
  "text_body": "Ofertas: até 50% off.",
  "status": "R",
  "recipients": 0,
  "sent": 0,
  "failed": 0,
  "scheduled_at": "2026-11-27T12:00:00Z",
  "created_at": "2026-10-11T21:05:13.511196Z",
  "updated_at": "2026-10-11T21:05:13.511196Z"
}

Campos da resposta

iduuid
Identificador da campanha.
subjectstring
Assunto do e-mail.
html_bodystring
Corpo em HTML.
text_bodystring
Versão em texto puro.
statusstring
Letra do estado: R rascunho, S enviando, A enviada, F falhou.
recipientsinteger
Quantidade de inscritos ativos no momento do envio. 0 antes de enviar.
sentinteger
E-mails entregues ao provedor até agora.
failedinteger
E-mails que falharam até agora.
scheduled_atstring
Data informada para o envio. Apenas registro: não dispara nada sozinha.
sent_atstring
Quando o envio começou. Ausente em rascunho.
vendor_iduuid
Seller dono da campanha. Ausente em campanha da loja.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros (Criar campanha)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_newsletter","manage_content"]}
400Corpo inválido, ou falta subject.{"error":"subject is required"}
500Falha ao gravar.{"error":"failed to create campaign","detail":"..."}
scheduled_at não agenda o envio

Não existe disparo automático por data. Para enviar, chame POST /api/v1/admin/newsletter/campaigns/{id}/send (por você, ou por um agendador seu).

Atualizar campanha

Atualiza só os campos enviados, e só enquanto a campanha é rascunho (R). Campanhas enviando, enviadas ou que falharam não podem ser editadas.

PUT/api/v1/admin/newsletter/campaigns/{id}Admin

Altera uma campanha em rascunho

Rota ligada ao módulo newsletter: com o módulo desligado a resposta é 403. Exige manage_newsletter ou manage_content.

Parâmetros de caminho

iduuidobrigatório
Identificador da campanha.

Corpo da requisição

subjectstring
Novo assunto.
html_bodystring
Novo corpo HTML.
text_bodystring
Nova versão em texto.
scheduled_atstring
Nova data prevista (RFC 3339).

Exemplo de requisição (Atualizar campanha)

bash
curl -X PUT "$BASE_URL/api/v1/admin/newsletter/campaigns/b2247714-08c6-4ad9-b644-748eae7baa70" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "subject": "Black Friday chegou: só hoje"
}'

Resposta (Atualizar campanha)

200Campanha atualizada
json
{
  "id": "b2247714-08c6-4ad9-b644-748eae7baa70",
  "subject": "Black Friday chegou: só hoje",
  "html_body": "<h1>Ofertas</h1><p>Até 50% off.</p>",
  "text_body": "Ofertas: até 50% off.",
  "status": "R",
  "recipients": 0,
  "sent": 0,
  "failed": 0,
  "scheduled_at": "2026-11-27T12:00:00Z",
  "created_at": "2026-10-11T21:05:13.511196Z",
  "updated_at": "2026-10-11T21:05:13.511196Z"
}

Campos da resposta

iduuid
Identificador da campanha.
subjectstring
Assunto do e-mail.
html_bodystring
Corpo em HTML.
text_bodystring
Versão em texto puro.
statusstring
Letra do estado: R rascunho, S enviando, A enviada, F falhou.
recipientsinteger
Quantidade de inscritos ativos no momento do envio. 0 antes de enviar.
sentinteger
E-mails entregues ao provedor até agora.
failedinteger
E-mails que falharam até agora.
scheduled_atstring
Data informada para o envio. Apenas registro: não dispara nada sozinha.
sent_atstring
Quando o envio começou. Ausente em rascunho.
vendor_iduuid
Seller dono da campanha. Ausente em campanha da loja.
created_atstring
Criação, RFC 3339.
updated_atstring
Última alteração, RFC 3339.

Erros (Atualizar campanha)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_newsletter","manage_content"]}
400A campanha não está em rascunho.{"error":"can only edit draft campaigns (current status: A)"}
404Não existe campanha com esse id.{"error":"campaign not found"}
500Corpo sem nenhum campo (no fields to update), ou falha de banco.{"error":"failed to update campaign","detail":"no fields to update"}

Apagar campanha

Só campanhas em rascunho (R) ou que falharam (F) podem ser apagadas. Campanhas já enviadas ficam como histórico.

DELETE/api/v1/admin/newsletter/campaigns/{id}Admin

Apaga uma campanha em rascunho ou que falhou

Rota ligada ao módulo newsletter: com o módulo desligado a resposta é 403. Exige manage_newsletter ou manage_content.

Parâmetros de caminho

iduuidobrigatório
Identificador da campanha.

Exemplo de requisição (Apagar campanha)

bash
curl -X DELETE "$BASE_URL/api/v1/admin/newsletter/campaigns/b2247714-08c6-4ad9-b644-748eae7baa70" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Apagar campanha)

200Campanha apagada
json
{
  "message": "campaign deleted"
}

Erros (Apagar campanha)

StatusQuandoExemplo de corpo
401Token ausente, inválido ou expirado.{"error":"invalid or expired token"}
403O administrador não tem o privilégio exigido.{"error":"insufficient privileges","privilege_required_any":["manage_newsletter","manage_content"]}
400A campanha não existe ou não pode ser apagada (enviando ou enviada). Os dois casos usam a mesma mensagem.{"error":"campaign not found or cannot be deleted (only draft/failed campaigns can be deleted)"}
Exclusão definitiva

Não há como restaurar uma campanha apagada.

Veja também

  • Enviar campanha
  • Inscritos
Anterior
Exportar inscritos
Próxima
Enviar campanha
Nesta página
  • Listar campanhas
  • Exemplo de requisição (Listar campanhas)
  • Resposta (Listar campanhas)
  • Erros (Listar campanhas)
  • Consultar campanha
  • Exemplo de requisição (Consultar campanha)
  • Resposta (Consultar campanha)
  • Erros (Consultar campanha)
  • Criar campanha
  • Exemplo de requisição (Criar campanha)
  • Resposta (Criar campanha)
  • Erros (Criar campanha)
  • Atualizar campanha
  • Exemplo de requisição (Atualizar campanha)
  • Resposta (Atualizar campanha)
  • Erros (Atualizar campanha)
  • Apagar campanha
  • Exemplo de requisição (Apagar campanha)
  • Resposta (Apagar campanha)
  • Erros (Apagar campanha)
  • Veja também