> ## Documentation Index
> Fetch the complete documentation index at: https://docs.robbu.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Importar Contatos para Mailing

> API para importar contatos em lote para um mailing.

## 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

```bash theme={null}
POST https://api.orion.robbu.global/mailing/contacts
```

### Headers

```http theme={null}
Content-Type: application/json
```

***

# Estrutura da Requisição

## Body

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "mailingId": "m_20260305_143022_1a2b3c",
  "created": true,
  "saved": 1,
  "closed": false
}
```

***

## 2 — Adicionar contatos ao mailing

Utilize o `mailingId` retornado anteriormente.

### Request

```json theme={null}
{
  "mailingId": "m_20260305_143022_1a2b3c",
  "contacts": [
    {
      "tipo_de_registro": "TELEFONE",
      "valor_do_registro": "11977776666",
      "nome_cliente": "Pedro Oliveira",
      "cpfcnpj": ""
    }
  ]
}
```

### Response

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "message": "contacts é obrigatório e deve conter pelo menos 1 contato."
}
```

## Limite excedido

```json theme={null}
{
  "message": "Máximo de 1000 contatos por request."
}
```

## Contrato inválido de contato

```json theme={null}
{
  "message": "Contato inválido: tipo_de_registro deve ser TELEFONE ou EMAIL."
}
```

## Valor incompatível com o tipo\_de\_registro

```json theme={null}
{
  "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

```json theme={null}
{
  "message": "Contato inválido: cpfcnpj informado é inválido."
}
```

## Mailing fechado

```json theme={null}
{
  "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