postal
Pedir acesso
Audiência

Propriedades de contato

Campos personalizados dos contatos, com tipo e valor padrão.

Propriedades são os campos personalizados dos contatos, como plano, cidade ou data de nascimento. Defina a chave e o tipo uma vez; depois, use a chave em properties ao criar ou atualizar contatos, nas importações e nos campos dos formulários. Cada time pode ter até 100 propriedades. Nos endpoints com {id}, você pode usar o ID ou a chave.

#Tipos e conversão

TipoValores aceitosGuardado como
stringTexto, até 1.000 caracteres.Texto, sem espaços nas pontas.
number42, "42", "1234,56" ou "1234.56".Número inteiro ou decimal.
booleantrue/false, "sim"/"não", "yes"/"no", "1"/"0", "on"/"off".true ou false.
date"2024-03-18", "18/03/2024" ou outra data reconhecível.AAAA-MM-DD.

Um valor vazio (null ou "") apaga a propriedade do contato. Valores que não podem ser convertidos geram 422.

#Listar propriedades

GET/contact-properties

Chave de acesso total

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.
GET /contact-properties

cURL

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

Node.js

const response = await fetch('https://api.postal.so/contact-properties', {
  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/contact-properties",
    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('contact-properties', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);
200Resposta
{
  "object": "list",
  "has_more": false,
  "data": [
    {
      "object": "contact_property",
      "id": "019a1d80-5d6e-7f80-8a9b-0c1d2e3f4a5b",
      "key": "plan",
      "type": "string",
      "fallback_value": "free",
      "created_at": "2026-10-20T09:00:00.000000Z",
      "updated_at": "2026-10-20T09:00:00.000000Z"
    }
  ]
}

#Criar uma propriedade

POST/contact-properties

Chave de acesso total

A chave e o tipo não podem mudar depois, porque os contatos já guardam valores daquele tipo.

Corpo da requisição

  • keystringobrigatório
    Letras minúsculas, números e _, começando com letra, até 64 caracteres. Não pode ser id, email, first_name, last_name, unsubscribed, created_at, updated_at, properties, segments nem topics.
  • typestringobrigatório
    string, number, boolean ou date.
  • fallback_valuestring | number | boolean | null
    Valor usado quando o contato não tem a propriedade (por exemplo, ao personalizar envios).

Erros

  • 422validation_error
    Chave inválida, reservada ou já usada, tipo inválido, valor padrão incompatível com o tipo, ou o time já tem 100 propriedades.
POST /contact-properties

cURL

curl -X POST https://api.postal.so/contact-properties \
  -H "Authorization: Bearer $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "plan",
    "type": "string",
    "fallback_value": "free"
  }'

Node.js

const response = await fetch('https://api.postal.so/contact-properties', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    key: 'plan',
    type: 'string',
    fallback_value: 'free',
  }),
});

const data = await response.json();

Python

import os
import requests

response = requests.post(
    "https://api.postal.so/contact-properties",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    json={
        "key": "plan",
        "type": "string",
        "fallback_value": "free",
    },
    timeout=10,
)

data = response.json()

PHP

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

$response = $client->post('contact-properties', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
    'json' => [
        'key' => 'plan',
        'type' => 'string',
        'fallback_value' => 'free',
    ],
]);

$data = json_decode($response->getBody(), true);
201Resposta
{
  "object": "contact_property",
  "id": "019a1d80-5d6e-7f80-8a9b-0c1d2e3f4a5b"
}

#Obter uma propriedade

GET/contact-properties/{id}

Chave de acesso total

Parâmetros de caminho

  • idstringobrigatório
    ID ou chave.

Erros

  • 404not_found
    O recurso não existe ou é de outro time.
GET /contact-properties/{id}

cURL

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

Node.js

const response = await fetch('https://api.postal.so/contact-properties/plan', {
  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/contact-properties/plan",
    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('contact-properties/plan', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);
200Resposta
{
  "object": "contact_property",
  "id": "019a1d80-5d6e-7f80-8a9b-0c1d2e3f4a5b",
  "key": "plan",
  "type": "string",
  "fallback_value": "free",
  "created_at": "2026-10-20T09:00:00.000000Z",
  "updated_at": "2026-10-20T09:00:00.000000Z"
}

#Atualizar uma propriedade

PATCH/contact-properties/{id}

Chave de acesso total

Só o valor padrão pode mudar. Enviar key ou type gera 422.

Parâmetros de caminho

  • idstringobrigatório
    ID ou chave.

Corpo da requisição

  • fallback_valuestring | number | boolean | null
    Novo valor padrão; null remove.

Erros

  • 422validation_error
    Algum campo é inválido. A mensagem diz qual.
  • 404not_found
    O recurso não existe ou é de outro time.
PATCH /contact-properties/{id}

cURL

curl -X PATCH https://api.postal.so/contact-properties/plan \
  -H "Authorization: Bearer $POSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fallback_value": "pro"
  }'

Node.js

const response = await fetch('https://api.postal.so/contact-properties/plan', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${process.env.POSTAL_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fallback_value: 'pro',
  }),
});

const data = await response.json();

Python

import os
import requests

response = requests.patch(
    "https://api.postal.so/contact-properties/plan",
    headers={"Authorization": f"Bearer {os.environ['POSTAL_API_KEY']}"},
    json={
        "fallback_value": "pro",
    },
    timeout=10,
)

data = response.json()

PHP

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

$response = $client->patch('contact-properties/plan', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
    'json' => [
        'fallback_value' => 'pro',
    ],
]);

$data = json_decode($response->getBody(), true);
200Resposta
{
  "object": "contact_property",
  "id": "019a1d80-5d6e-7f80-8a9b-0c1d2e3f4a5b"
}

#Excluir uma propriedade

DELETE/contact-properties/{id}

Chave de acesso total

Remove a definição na hora; os valores que os contatos tinham são apagados em segundo plano.

Parâmetros de caminho

  • idstringobrigatório
    ID ou chave.

Erros

  • 404not_found
    O recurso não existe ou é de outro time.
DELETE /contact-properties/{id}

cURL

curl -X DELETE https://api.postal.so/contact-properties/plan \
  -H "Authorization: Bearer $POSTAL_API_KEY"

Node.js

const response = await fetch('https://api.postal.so/contact-properties/plan', {
  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/contact-properties/plan",
    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('contact-properties/plan', [
    'headers' => ['Authorization' => 'Bearer '.getenv('POSTAL_API_KEY')],
]);

$data = json_decode($response->getBody(), true);
200Resposta
{
  "object": "contact_property",
  "id": "019a1d80-5d6e-7f80-8a9b-0c1d2e3f4a5b",
  "deleted": true
}