Audiência

Segmentos

Listas de contatos para direcionar campanhas.

Segmentos são listas de contatos, para direcionar campanhas. Um contato pode estar em vários segmentos. Adicione e remova contatos pelos endpoints de contatos, na importação ou com formulários. O plano Free permite até 3 segmentos; os planos pagos, quantos você quiser.

#Listar segmentos

GET/segments

Chave de acesso total

Cada segmento vem com contacts_count. Para ver os contatos, use GET /contacts?segment_id=….

Parâmetros de consulta

limitinteger
De 1 a 100. Padrão: 20.
afterstring
Cursor da próxima página.
beforestring
Cursor da página anterior.
searchstring
Busca no nome.

GET /segments

cURL

curl https://api.postal.so/segments \
  -H "Authorization: Bearer $POSTAL_API_KEY"

Node.js

const response = await fetch('https://api.postal.so/segments', {
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  },
});

const data = await response.json();

Python

import os
import requests

response = requests.get(
    "https://api.postal.so/segments",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->get('segments', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);

200Resposta

{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "segment",
      "id": "019a1d90-3b4c-7d5e-9f6a-7b8c9d0e1f2a",
      "name": "Clientes ativos",
      "description": "Compraram nos últimos 90 dias.",
      "contacts_count": 1284,
      "created_at": "2026-10-20T10:00:00.000000Z",
      "updated_at": "2026-10-20T10:00:00.000000Z"
    }
  ]
}

#Criar um segmento

POST/segments

Chave de acesso total

Corpo da requisição

namestringobrigatório
Nome, até 255 caracteres.
descriptionstring | null
Descrição, até 500 caracteres.

Erros

422validation_error
Algum campo é inválido. A mensagem diz qual.
403plan_limit_reached
O plano não permite mais segmentos.

POST /segments

cURL

curl -X POST https://api.postal.so/segments \
  -H "Authorization: Bearer $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clientes ativos",
    "description": "Compraram nos últimos 90 dias."
  }'

Node.js

const response = await fetch('https://api.postal.so/segments', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Clientes ativos',
    description: 'Compraram nos últimos 90 dias.',
  }),
});

const data = await response.json();

Python

import os
import requests

response = requests.post(
    "https://api.postal.so/segments",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    json={
        "name": "Clientes ativos",
        "description": "Compraram nos últimos 90 dias.",
    },
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->post('segments', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
    'json' => [
        'name' => 'Clientes ativos',
        'description' => 'Compraram nos últimos 90 dias.',
    ],
]);

$data = json_decode($response->getBody(), true);

201Resposta

{
  "object": "segment",
  "id": "019a1d90-3b4c-7d5e-9f6a-7b8c9d0e1f2a",
  "name": "Clientes ativos"
}

#Obter um segmento

GET/segments/{id}

Chave de acesso total

Parâmetros de caminho

idstringobrigatório
ID do segmento.

Erros

404not_found
O recurso não existe ou é de outro time.

GET /segments/{id}

cURL

curl https://api.postal.so/segments/019a1d90-3b4c-7d5e-9f6a-7b8c9d0e1f2a \
  -H "Authorization: Bearer $POSTAL_API_KEY"

Node.js

const response = await fetch('https://api.postal.so/segments/019a1d90-3b4c-7d5e-9f6a-7b8c9d0e1f2a', {
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  },
});

const data = await response.json();

Python

import os
import requests

response = requests.get(
    "https://api.postal.so/segments/019a1d90-3b4c-7d5e-9f6a-7b8c9d0e1f2a",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->get('segments/019a1d90-3b4c-7d5e-9f6a-7b8c9d0e1f2a', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);

200Resposta

{
  "object": "segment",
  "id": "019a1d90-3b4c-7d5e-9f6a-7b8c9d0e1f2a",
  "name": "Clientes ativos",
  "description": "Compraram nos últimos 90 dias.",
  "contacts_count": 1284,
  "created_at": "2026-10-20T10:00:00.000000Z",
  "updated_at": "2026-10-20T10:00:00.000000Z"
}

#Atualizar um segmento

PATCH/segments/{id}

Chave de acesso total

Parâmetros de caminho

idstringobrigatório
ID do segmento.

Corpo da requisição

namestring
Novo nome.
descriptionstring | null
Nova descrição.

Erros

422validation_error
Algum campo é inválido. A mensagem diz qual.
404not_found
O recurso não existe ou é de outro time.

PATCH /segments/{id}

cURL

curl -X PATCH https://api.postal.so/segments/019a1d90-3b4c-7d5e-9f6a-7b8c9d0e1f2a \
  -H "Authorization: Bearer $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Clientes ativos (90 dias)"
  }'

Node.js

const response = await fetch('https://api.postal.so/segments/019a1d90-3b4c-7d5e-9f6a-7b8c9d0e1f2a', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Clientes ativos (90 dias)',
  }),
});

const data = await response.json();

Python

import os
import requests

response = requests.patch(
    "https://api.postal.so/segments/019a1d90-3b4c-7d5e-9f6a-7b8c9d0e1f2a",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    json={
        "name": "Clientes ativos (90 dias)",
    },
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->patch('segments/019a1d90-3b4c-7d5e-9f6a-7b8c9d0e1f2a', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
    'json' => [
        'name' => 'Clientes ativos (90 dias)',
    ],
]);

$data = json_decode($response->getBody(), true);

200Resposta

{
  "object": "segment",
  "id": "019a1d90-3b4c-7d5e-9f6a-7b8c9d0e1f2a"
}

#Excluir um segmento

DELETE/segments/{id}

Chave de acesso total

Apaga só a lista: os contatos continuam na audiência. Um segmento que recebe os contatos de um formulário não pode ser excluído; troque o segmento do formulário antes.

Parâmetros de caminho

idstringobrigatório
ID do segmento.

Erros

409segment_in_use
Algum formulário envia contatos para este segmento.
404not_found
O recurso não existe ou é de outro time.

DELETE /segments/{id}

cURL

curl -X DELETE https://api.postal.so/segments/019a1d90-3b4c-7d5e-9f6a-7b8c9d0e1f2a \
  -H "Authorization: Bearer $POSTAL_API_KEY"

Node.js

const response = await fetch('https://api.postal.so/segments/019a1d90-3b4c-7d5e-9f6a-7b8c9d0e1f2a', {
  method: 'DELETE',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
  },
});

const data = await response.json();

Python

import os
import requests

response = requests.delete(
    "https://api.postal.so/segments/019a1d90-3b4c-7d5e-9f6a-7b8c9d0e1f2a",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    timeout=10,
)

data = response.json()

PHP

$client = new \GuzzleHttp\Client(['base_uri' => 'https://api.postal.so']);

$response = $client->delete('segments/019a1d90-3b4c-7d5e-9f6a-7b8c9d0e1f2a', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);

200Resposta

{
  "object": "segment",
  "id": "019a1d90-3b4c-7d5e-9f6a-7b8c9d0e1f2a",
  "deleted": true
}