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

Campo	Tipo	Obrigatório	Descrição
mailingId	string	Não*	Identificador do mailing
segmentCode	string	Sim**	Código do segmento
templateGroup	string	Sim**	Grupo de templates
close	boolean	Não	Fecha o mailing após inserir contatos
contacts	array	Sim	Lista de contatos
contacts[].tipo_de_registro	string	Sim	Tipo do contato: `TELEFONE` ou `EMAIL`
contacts[].valor_do_registro	string	Sim	Valor do contato: telefone válido quando `tipo_de_registro` for `TELEFONE`, ou e-mail válido quando for `EMAIL`
contacts[].nome_cliente	string	Sim	Nome do cliente
contacts[].cpfcnpj	string	Não	CPF/CNPJ válido (quando informado)
contacts[].mensagem	string	Não	Campo adicional de mensagem
contacts[].codcliente	string	Não	Código do cliente
contacts[].tag	string	Não	Tag associada ao contato
contacts[].coringa1..coringa5	string	Não	Campos 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

Status	Descrição
200	Operação realizada com sucesso
400	Requisição inválida
409	Mailing já está fechado
500	Erro 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

​Visão Geral

​Endpoint

​Headers

​Estrutura da Requisição

​Body

​Parâmetros

​Observação sobre os campos do contato

​Fluxo de Uso

​1 — Criar um novo mailing

​Request

​Response

​2 — Adicionar contatos ao mailing

​Request

​Response

​3 — Fechar o mailing

​Request

​Response

​Regras Importantes

​Códigos de Resposta

​Exemplos de Erro

​Contatos ausentes

​Limite excedido

​Contrato inválido de contato

​Valor incompatível com o tipo_de_registro

​CPF/CNPJ inválido

​Mailing fechado

​Boas Práticas

Visão Geral

Endpoint

Headers

Estrutura da Requisição

Body

Parâmetros

Observação sobre os campos do contato

Fluxo de Uso

1 — Criar um novo mailing

Request

Response

2 — Adicionar contatos ao mailing

Request

Response

3 — Fechar o mailing

Request

Response

Regras Importantes

Códigos de Resposta

Exemplos de Erro

Contatos ausentes

Limite excedido

Contrato inválido de contato

Valor incompatível com o tipo_de_registro

CPF/CNPJ inválido

Mailing fechado

Boas Práticas