Pular para o conteúdo

Criar um rascunho de campanha de e-mail

POST
/email-campaigns
 
curl --request POST \
  --url https://dattacrm.com.br/api/v1/email-campaigns \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "subject": "", "preheader": "", "html": "example", "text": "", "includeListIds": [ "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f" ], "excludeListIds": [ "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f" ], "includeTags": [ "example" ], "excludeTags": [ "example" ], "audienceMatch": "any", "audienceFilter": { "signup": { "from": "example", "to": "example", "utmField": "source", "utmValue": "example", "pageContains": "example" }, "purchase": { "mode": "bought", "productName": "example", "maxValue": 1 } }, "utm": { "enabled": true, "source": "example", "medium": "example", "campaign": "example", "content": "example", "term": "example" }, "desiredSendAt": "2026-10-19T12:00:00.000Z" }'

Cria um rascunho de campanha de e-mail em HTML, com público (listas e tags) e, se quiser, um horário de envio sugerido (desiredSendAt). A API nunca agenda, testa nem envia: o rascunho fica em draft até uma pessoa revisar, testar e agendar no CRM, pelo endereço editUrl; a tela propõe o horário sugerido ao agendar. O HTML é sanitizado ao gravar (scripts saem). O rascunho nasce com rastreamento de aberturas e cliques ligado e a identidade vazia. Devolve estimatedRecipients, quantos leads receberiam hoje. Responde 400 quando o HTML fica vazio depois de sanitizado (details.code = email_html_empty), quando uma lista não é da conta (audience_list_invalid) ou quando desiredSendAt não está entre agora e 365 dias à frente.

Authorizations

Seção intitulada “Authorizations ”

Request Body required

Seção intitulada “Request Body required ”
Media type application/json

Rascunho de campanha em HTML. Obrigatórios: name e html. O rascunho nasce com rastreamento de aberturas e cliques ligado e a identidade vazia; uma pessoa revisa, testa e agenda na tela.

object
name
required

Nome interno da campanha (1 a 150 caracteres, sem quebra de linha).

string
>= 1 characters <= 150 characters
subject

Assunto do e-mail (até 200 caracteres, sem quebra de linha).

string
"" <= 200 characters
preheader

Pré-cabeçalho, o texto curto depois do assunto na caixa de entrada (até 250 caracteres, sem quebra de linha).

string
"" <= 250 characters
html
required

Conteúdo HTML do e-mail (até 100 mil caracteres). É sanitizado ao gravar: scripts e atributos perigosos saem, e um HTML que fica vazio é recusado. Use {{first_name}} ou {{name}} para personalizar.

string
>= 1 characters <= 100000 characters
text

Versão em texto puro (até 100 mil caracteres). Vazia: no envio, ela é gerada a partir do HTML.

string
"" <= 100000 characters
includeListIds

Listas cujos leads recebem a campanha (até 50, da própria conta; veja list_lists). O rascunho pode nascer sem lista, mas só é agendado na tela com pelo menos uma.

Array<string>
<= 50 items
excludeListIds

Listas cujos leads ficam de fora (até 50, da própria conta).

Array<string>
<= 50 items
includeTags

Tags cujos leads recebem a campanha (até 50), combinadas com as listas incluídas conforme audienceMatch.

Array<string>
<= 50 items
excludeTags

Tags cujos leads ficam de fora (até 50).

Array<string>
<= 50 items
audienceMatch

Como as listas e tags incluídas se combinam: any (qualquer critério: está em alguma lista ou tem alguma tag) ou all (todos os critérios: está em todas as listas e tem todas as tags). As exclusões valem nos dois. Padrão: any.

string
Allowed values: any all
audienceFilter

Filtros além de listas e tags; {} sem filtro. signup (cadastro): período from/to em AAAA-MM-DD no dia de São Paulo, utmField (source, medium, campaign, content ou term) com utmValue (sem diferenciar maiúsculas) e pageContains (trecho do endereço da página), tudo no mesmo cadastro. purchase (compra): mode bought (comprou) ou not_bought (não comprou), com productName e maxValue (valor da venda até, sem order bump) na mesma venda aprovada. Na edição, o filtro enviado substitui o atual inteiro. Padrão: {}.

object
signup

Cadastro: entra quem tem um cadastro que atende a todos os campos preenchidos.

object
from

Primeiro dia do cadastro (AAAA-MM-DD, dia de São Paulo), inclusive.

string
/^\d{4}-\d{2}-\d{2}$/
to

Último dia do cadastro (AAAA-MM-DD, dia de São Paulo), inclusive.

string
/^\d{4}-\d{2}-\d{2}$/
utmField

Qual UTM do cadastro comparar: source, medium, campaign, content ou term.

string
Allowed values: source medium campaign content term
utmValue

Valor da UTM, sem diferenciar maiúsculas (até 200 caracteres). Exige utmField.

string
<= 200 characters
pageContains

Trecho do endereço da página do cadastro (até 500 caracteres).

string
<= 500 characters
purchase

Compra: considera só vendas aprovadas, venda a venda.

object
mode
required

Bought (comprou) ou not_bought (não comprou).

string
Allowed values: bought not_bought
productName

Nome do produto, como chega do gateway (até 300 caracteres).

string
<= 300 characters
maxValue

Valor da venda até, em reais, sem order bump.

number
<= 10000000
utm

UTMs acrescentadas aos links do e-mail. Com enabled: true, source, medium e campaign são obrigatórios.

object
enabled

Liga as UTMs nos links do e-mail.

boolean
source

Utm_source (até 200 caracteres).

string
<= 200 characters
medium

Utm_medium (até 200 caracteres).

string
<= 200 characters
campaign

Utm_campaign (até 200 caracteres).

string
<= 200 characters
content

Utm_content (até 200 caracteres).

string
<= 200 characters
term

Utm_term (até 200 caracteres).

string
<= 200 characters
desiredSendAt
Any of:

Data e hora em ISO 8601, com fuso.

string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
Example 
2026-10-19T12:00:00.000Z

Responses

Seção intitulada “ Responses ”

201

Seção intitulada “201 ”

Sucesso.

Media type application/json
object
data
required

Campanha de e-mail da conta.

object
id
required

Identificador da campanha.

string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
name
required

Nome interno da campanha, como aparece no CRM.

string
subject
required

Assunto do e-mail.

string
preheader
required

Pré-cabeçalho: o texto curto que aparece depois do assunto na caixa de entrada.

string
html
required

Conteúdo HTML do e-mail, já sanitizado (sem scripts).

string
text
required

Versão em texto puro. Vazia: no envio, ela é gerada a partir do HTML.

string
state
required

Situação: draft (rascunho, editável pela API), scheduled (agendada na tela), running (enviando), paused (pausada), completed (concluída) ou cancelled (cancelada).

string
Allowed values: draft scheduled running paused completed cancelled
includeListIds
required

Listas cujos leads recebem a campanha.

Array<string>
excludeListIds
required

Listas cujos leads ficam de fora, mesmo que estejam numa lista ou tag incluída.

Array<string>
includeTags
required

Tags cujos leads recebem a campanha, combinadas com as listas incluídas conforme audienceMatch.

Array<string>
excludeTags
required

Tags cujos leads ficam de fora.

Array<string>
audienceMatch
required

Como as listas e tags incluídas se combinam: any (qualquer critério: está em alguma lista ou tem alguma tag) ou all (todos os critérios: está em todas as listas e tem todas as tags). As exclusões valem nos dois.

string
Allowed values: any all
audienceFilter
required

Filtros além de listas e tags; {} sem filtro. signup (cadastro): período from/to em AAAA-MM-DD no dia de São Paulo, utmField (source, medium, campaign, content ou term) com utmValue (sem diferenciar maiúsculas) e pageContains (trecho do endereço da página), tudo no mesmo cadastro. purchase (compra): mode bought (comprou) ou not_bought (não comprou), com productName e maxValue (valor da venda até, sem order bump) na mesma venda aprovada.

object
signup

Cadastro: entra quem tem um cadastro que atende a todos os campos preenchidos.

object
from

Primeiro dia (AAAA-MM-DD), inclusive.

string
to

Último dia (AAAA-MM-DD), inclusive.

string
utmField

Qual UTM do cadastro comparar.

string
Allowed values: source medium campaign content term
utmValue

Valor da UTM.

string
pageContains

Trecho do endereço da página do cadastro.

string
purchase

Compra: considera só vendas aprovadas, venda a venda.

object
mode
required

Bought (comprou) ou not_bought (não comprou).

string
Allowed values: bought not_bought
productName

Nome do produto, como chega do gateway.

string
maxValue

Valor da venda até (R$).

number
utm
required

UTMs aplicadas aos links do e-mail no envio.

object
enabled
required

Se as UTMs são acrescentadas aos links do e-mail.

boolean
source
required

Utm_source.

string
medium
required

Utm_medium.

string
campaign
required

Utm_campaign.

string
content
required

Utm_content.

string
term
required

Utm_term.

string
suggestedSendAt
required
Any of:

Data e hora em ISO 8601, com fuso.

string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
scheduledAt
required
Any of:

Data e hora em ISO 8601, com fuso.

string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
createdAt
required

Quando a campanha foi criada.

string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
updatedAt
required

Última alteração da campanha.

string format: date-time
/^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$/
editUrl
required

Endereço da campanha no CRM, onde uma pessoa revisa, testa e agenda o envio; null quando o endereço público do CRM não está configurado.

string | null
estimatedRecipients
required
Any of:
integer
>= -9007199254740991 <= 9007199254740991
Example 
{
  "data": {
    "id": "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f",
    "state": "draft",
    "includeListIds": [
      "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f"
    ],
    "excludeListIds": [
      "0b6f3c1e-8a4d-4f5b-9c2e-1a2b3c4d5e6f"
    ],
    "audienceMatch": "any",
    "audienceFilter": {
      "signup": {
        "utmField": "source"
      },
      "purchase": {
        "mode": "bought"
      }
    },
    "suggestedSendAt": "2026-10-19T12:00:00.000Z",
    "scheduledAt": "2026-10-19T12:00:00.000Z",
    "createdAt": "2026-10-19T12:00:00.000Z",
    "updatedAt": "2026-10-19T12:00:00.000Z"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

X-RateLimit-Limit
integer

Máximo de requisições por janela de 60 segundos para esta chave.

X-RateLimit-Remaining
integer

Requisições restantes na janela atual.

X-RateLimit-Reset
integer

Fim da janela atual, em milissegundos desde a época Unix (epoch ms).

400

Seção intitulada “400 ”

Dados inválidos na requisição (validation_error), lead novo sem lista (list_required), campo que mudou de lugar (field_moved) ou chave enviada na URL (api_key_in_url).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

401

Seção intitulada “401 ”

Chave ausente, inválida (invalid_api_key), vencida (api_key_expired) ou revogada (api_key_revoked).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

403

Seção intitulada “403 ”

A chave é somente leitura e a operação grava dados (insufficient_scope).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

409

Seção intitulada “409 ”

Conflito com o estado atual (conflict), contato oculto, cujo negócio não muda (lead_hidden), ou limite do plano atingido (plan_limit).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

413

Seção intitulada “413 ”

O corpo da requisição passa de 256 KB (payload_too_large).

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

429

Seção intitulada “429 ”

Limite de requisições atingido (rate_limited). Aguarde Retry-After segundos.

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

X-RateLimit-Limit
integer

Máximo de requisições por janela de 60 segundos para esta chave.

X-RateLimit-Remaining
integer

Requisições restantes na janela atual.

X-RateLimit-Reset
integer

Fim da janela atual, em milissegundos desde a época Unix (epoch ms).

Retry-After
integer

Segundos até poder tentar de novo.

500

Seção intitulada “500 ”

Erro interno (internal_error). Informe o requestId ao suporte.

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

503

Seção intitulada “503 ”

O CRM está em modo somente leitura durante uma migração (maintenance). Tente de novo depois de Retry-After segundos.

Media type application/json

Formato de erro da API.

object
error
required
object
code
required

Código estável do erro, ex.: validation_error.

string
message
required

Mensagem legível em português.

string
details

Detalhes extras, ex.: lista de campos inválidos.

requestId
required

Identificador da requisição, para suporte.

string
Example generated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": "example",
    "requestId": "example"
  }
}

Headers

Seção intitulada “Headers ”
X-Request-Id
string

Identificador da requisição, para suporte.

Retry-After
integer

Segundos até poder tentar de novo.