Skip to main content

​
Visão Geral

A API permite importar contatos em lote para um mailing. Principais características:
  • Importação de até 1000 contatos por requisição
  • Criação automática de mailing no primeiro envio
  • Envio incremental de contatos
  • Possibilidade de fechar o mailing quando a importação terminar

​
Endpoint

POST https://api.orion.robbu.global/mailing/contacts

​
Headers

Content-Type: application/json

​
Estrutura da Requisição

​
Body

{
  "mailingId": "m_20260305_143022_abc123",
  "segmentCode": "SEG001",
  "templateGroup": "TEMPLATE_GROUP_01",
  "close": false,
  "contacts": [
    {
      "tipo_de_registro": "EMAIL",
      "valor_do_registro": "ana@example.com",
      "nome_cliente": "Ana Costa",
      "cpfcnpj": "12345678900",
      "codcliente": "",
      "tag": "",
      "coringa1": "",
      "coringa2": "",
      "coringa3": "",
      "coringa4": "",
      "coringa5": ""
    }
  ]
}

​
Parâmetros

CampoTipoObrigatórioDescrição
mailingIdstringNão*Identificador do mailing
segmentCodestringSim**Código do segmento
templateGroupstringSim**Grupo de templates
closebooleanNãoFecha o mailing após inserir contatos
contactsarraySimLista de contatos
contacts[].tipo_de_registrostringSimTipo do contato: TELEFONE ou EMAIL
contacts[].valor_do_registrostringSimValor do contato: telefone válido quando tipo_de_registro for TELEFONE, ou e-mail válido quando for EMAIL
contacts[].nome_clientestringSimNome do cliente
contacts[].cpfcnpjstringNãoCPF/CNPJ válido (quando informado)
contacts[].mensagemstringNãoCampo adicional de mensagem
contacts[].codclientestringNãoCódigo do cliente
contacts[].tagstringNãoTag associada ao contato
contacts[].coringa1..coringa5stringNãoCampos coringa para uso livre
* obrigatório a partir do segundo envio
** obrigatório apenas no primeiro envio

​
Observação sobre os campos do contato

Os campos de contacts não precisam ser enviados em maiúsculo. Exemplo válido: tipo_de_registro e TIPO_DE_REGISTRO. Também são válidos os valores telefone e email em tipo_de_registro.

​
Fluxo de Uso

​
1 — Criar um novo mailing

Se mailingId não for enviado, um mailing será criado automaticamente.

​
Request

{
  "segmentCode": "PROMO_2026",
  "templateGroup": "EMAIL_MARKETING",
  "contacts": [
    {
      "tipo_de_registro": "EMAIL",
      "valor_do_registro": "maria@example.com",
      "nome_cliente": "Maria Santos",
      "cpfcnpj": "12345678900",
      "tag": "lead_novo"
    }
  ]
}

​
Response

{
  "mailingId": "m_20260305_143022_1a2b3c",
  "created": true,
  "saved": 1,
  "closed": false
}

​
2 — Adicionar contatos ao mailing

Utilize o mailingId retornado anteriormente.

​
Request

{
  "mailingId": "m_20260305_143022_1a2b3c",
  "contacts": [
    {
      "tipo_de_registro": "TELEFONE",
      "valor_do_registro": "11977776666",
      "nome_cliente": "Pedro Oliveira",
      "cpfcnpj": ""
    }
  ]
}

​
Response

{
  "mailingId": "m_20260305_143022_1a2b3c",
  "created": false,
  "saved": 1,
  "closed": false
}

​
3 — Fechar o mailing

Quando terminar de enviar os contatos, utilize close: true.

​
Request

{
  "mailingId": "m_20260305_143022_1a2b3c",
  "close": true,
  "contacts": [
    {
      "tipo_de_registro": "EMAIL",
      "valor_do_registro": "ana@example.com",
      "nome_cliente": "Ana Costa",
      "cpfcnpj": "45612378900"
    }
  ]
}

​
Response

{
  "mailingId": "m_20260305_143022_1a2b3c",
  "created": false,
  "saved": 1,
  "closed": true
}
Após o mailing ser fechado não será possível adicionar novos contatos.

​
Regras Importantes

  • Máximo de 1000 contatos por request
  • tipo_de_registro deve ser TELEFONE ou EMAIL
  • valor_do_registro deve ser um telefone válido quando o tipo for TELEFONE, ou um e-mail válido quando o tipo for EMAIL
  • nome_cliente deve conter o nome do cliente
  • cpfcnpj é opcional, mas quando enviado deve ser um CPF/CNPJ válido
  • Os demais campos são opcionais
  • Mailings fechados não aceitam novos contatos

​
Códigos de Resposta

StatusDescrição
200Operação realizada com sucesso
400Requisição inválida
409Mailing já está fechado
500Erro interno

​
Exemplos de Erro

​
Contatos ausentes

{
  "message": "contacts é obrigatório e deve conter pelo menos 1 contato."
}

​
Limite excedido

{
  "message": "Máximo de 1000 contatos por request."
}

​
Contrato inválido de contato

{
  "message": "Contato inválido: tipo_de_registro deve ser TELEFONE ou EMAIL."
}

​
Valor incompatível com o tipo_de_registro

{
  "message": "Contato inválido: valor_do_registro deve ser telefone válido para TELEFONE ou e-mail válido para EMAIL."
}

​
CPF/CNPJ inválido

{
  "message": "Contato inválido: cpfcnpj informado é inválido."
}

​
Mailing fechado

{
  "mailingId": "m_20260305_143022_abc123",
  "message": "Este mailing já está fechado e não aceita novos contatos."
}

​
Boas Práticas

  • Utilize batches entre 500 e 1000 contatos
  • Guarde o mailingId retornado na primeira requisição
  • Apenas envie close: true quando tiver certeza de que não haverá novos contatos