POST/v1/campaigns

Criar campanha

Cria uma campanha como rascunho, dispara na hora ou agenda o envio. O título do conteúdo também vira o nome da campanha no painel.

Com action: "send" a campanha entra na fila de envio na mesma hora. Com action: "schedule" ela fica queued até scheduled_at; o agendador confere as campanhas vencidas a cada minuto.

Sem segment_id, o público é todo assinante com dispositivo ativo. Quem desativou a category informada fica de fora. A category precisa estar cadastrada no site; uma chave desconhecida recebe 422.

scheduled_at sem fuso é lido no fuso do site (padrão America/Sao_Paulo).

Send request

Use the documented inputs to call this endpoint directly.

API serverbase URL

Bearer tokenchaveSecretaoptional

Stored only in this browser for the chaveSecreta security scheme and reused on every API page in this group.

Parameters

Values are applied to the request and the example on the right.

Idempotency-Keyheader · stringoptional

Valor único por campanha, até 255 caracteres. Repetir a chamada com a mesma chave e o mesmo corpo em até 24 horas devolve a resposta original (com Idempotent-Replayed: true) em vez de criar outra campanha. A mesma chave com outro corpo recebe 422.

Request body

application/jsonrequired

actionenumoptional

draft salva como rascunho, send envia agora e schedule agenda para scheduled_at.

Values: "draft" · "send" · "schedule"

contentrequired

segment_idintegeroptional

ID de um segmento deste site. Sem ele, a campanha vai para todos os assinantes ativos.

categorystringoptional

Chave de uma categoria cadastrada no site, até 255 caracteres. Assinantes que desativaram essa categoria não recebem. Uma chave que não existe no site recebe 422.

scheduled_atstring · date-timeoptional

Data e hora do envio. Obrigatório com action: "schedule". Com fuso (-03:00 ou Z), vale o fuso informado; sem fuso, o horário é lido no fuso do site (padrão America/Sao_Paulo).

send_in_user_tzbooleanoptional

Entrega no mesmo horário de relógio de scheduled_at no fuso de cada assinante (estimado pelo país).

breakingbooleanoptional

Dá prioridade à campanha na fila de envio. Use para notícia urgente.

recurrenceenumoptional

Repete a campanha um dia ou uma semana depois de cada envio.

Values: "none" · "daily" · "weekly"

ab_testbooleanoptional

Ativa o teste A/B. Exige variants com pelo menos duas variantes.

test_fractionnumberoptional

Fração do público, entre 0 e 1, que recebe as variantes primeiro. Duas horas depois, a variante com mais cliques vai para o restante. Com 0 ou 1 não há segunda fase.

variantsarray<>optional

Variantes do teste A/B, no mínimo duas. Obrigatório quando ab_test é true.

Responses

201application/json

Campanha criada.

{
  "id": 1287,
  "status": "queued",
  "type": "scheduled"
}

idintegeroptional

ID da campanha.

statusenumoptional

draft para rascunho; queued para envio imediato ou agendado.

Values: "draft" · "queued"

typeenumoptional

Values: "instant" · "scheduled"

401application/json

Chave ausente, inválida ou revogada.

{
  "message": "Credencial ausente ou inválida."
}

messagestringoptional

Descrição do erro, em português. Quando a causa não tem mensagem própria, vem a mensagem padrão do código HTTP. Trate pelo código, não pelo texto.

422application/json

Algum campo não passou na validação. errors traz a mensagem de cada campo.

{
  "message": "O campo content.title é obrigatório.",
  "errors": {
    "content.title": [
      "O campo content.title é obrigatório."
    ]
  }
}

messagestringoptional

Primeira mensagem de erro.

errorsobjectoptional

Mensagens por campo. A chave é o caminho do campo com pontos, como content.title ou definition.groups.0.rules.1.op.

429application/json

Limite de requisições excedido. Espere os segundos indicados em Retry-After.

{
  "message": "Muitas requisições. Tente novamente em instantes."
}

messagestringoptional

Descrição do erro, em português. Quando a causa não tem mensagem própria, vem a mensagem padrão do código HTTP. Trate pelo código, não pelo texto.