API reference

Begin a sync

Open a full or delta sync before you push records.

Request

POSThttps://www.postaged.com/api/integrations/push/v1/sync

Opens a sync. A full sync marks every contact it did not receive as removed when it completes; a delta sync removes only what you delete. One sync can be open at a time, and an unfinished sync expires after 24 hours.

curl https://www.postaged.com/api/integrations/push/v1/sync \
  -H "Authorization: Bearer $POSTAGED_API_KEY" \
  -H "Idempotency-Key: 2026-10-03-begin-1" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "full"
  }'

const response = await fetch("https://www.postaged.com/api/integrations/push/v1/sync", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POSTAGED_API_KEY}`,
    "Idempotency-Key": "2026-10-03-begin-1",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mode: "full",
  }),
});
const result = await response.json();
console.log(result);

import os

import requests

response = requests.post(
    "https://www.postaged.com/api/integrations/push/v1/sync",
    headers={
        "Authorization": f"Bearer {os.environ['POSTAGED_API_KEY']}",
        "Idempotency-Key": "2026-10-03-begin-1",
    },
    json={
        "mode": "full",
    },
    timeout=300,
)
print(response.json())

Authentication

An integration key (it starts with pk_int_), created with New key on the integration's page. Send it in the Authorization: Bearer header. Only that integration's key works here; any other key gets 401 invalid_key.

Headers

Authorization: Bearer $POSTAGED_API_KEY
Content-Type: application/json

Parameters

Idempotency-Keystring (header)Required
A new value per request, and the same value when you retry that request. Up to 200 characters.

Request body

modestringOptional
full (the default) or delta. One of full or delta.

Request body

{
  "mode": "full"
}

Response 200

The sync is open.

syncIdstring
modestring
One of full or delta.
expiresAtstring

Response200 OK

{
  "syncId": "0b6f3c3e-8d2a-4f7e-9a51-2c4d8e6f1a20",
  "mode": "full",
  "expiresAt": "2026-10-04T14:05:00.000Z"
}

Errors

Errors use the body { "error": { "code", "message", "details" } }; details appears only on some codes. Full tables: Error reference.

Status	code	message	What to do
400	`invalid_json`	The request body must be JSON.	Send the body as JSON with a Content-Type of application/json.
400	`missing_idempotency_key`	Send an Idempotency-Key header so a retry cannot open a second sync.	Send an Idempotency-Key header with a new value for each request, and the same value when you retry that request.
401	`invalid_key`	That API key is not valid for this integration.	Send this integration's key (it starts with pk_int_) in the Authorization: Bearer header. A revoked key, another kind of key, or a key for a removed integration gets this error.
403	`integration_unavailable`	This integration is not accepting data. Contact support if you think that is wrong.	The integration is paused or disconnected in Postaged. Ask the owner to resume it, then send the request again.
409	`sync_in_progress`	A sync is already open for this integration. Complete it before beginning another.	Complete the open sync named in details.syncId, or wait for it to expire, then begin a new one.
409	`idempotency_key_reused`	That Idempotency-Key was used for a different request. Use a new key.	Use a new Idempotency-Key for this request. Reuse a key only to retry the same request with the same body.
409	`in_progress`	That request is still being processed.	The first attempt is still running. Wait a few seconds, then retry with the same Idempotency-Key to get its response.
429	`rate_limited`	Too many requests. Slow down and retry.	Wait the number of seconds in the Retry-After header, then send the request again.

invalid_json400

{
  "error": {
    "code": "invalid_json",
    "message": "The request body must be JSON."
  }
}

missing_idempotency_key400

{
  "error": {
    "code": "missing_idempotency_key",
    "message": "Send an Idempotency-Key header so a retry cannot open a second sync."
  }
}

invalid_key401

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Postaged"

{
  "error": {
    "code": "invalid_key",
    "message": "That API key is not valid for this integration."
  }
}

integration_unavailable403

{
  "error": {
    "code": "integration_unavailable",
    "message": "This integration is not accepting data. Contact support if you think that is wrong."
  }
}

sync_in_progress409

{
  "error": {
    "code": "sync_in_progress",
    "message": "A sync is already open for this integration. Complete it before beginning another.",
    "details": {
      "syncId": "0b6f3c3e-8d2a-4f7e-9a51-2c4d8e6f1a20",
      "mode": "full",
      "expiresAt": "2026-10-04T14:05:00.000Z"
    }
  }
}

idempotency_key_reused409

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "That Idempotency-Key was used for a different request. Use a new key."
  }
}

in_progress409

{
  "error": {
    "code": "in_progress",
    "message": "That request is still being processed."
  }
}

rate_limited429

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Slow down and retry."
  }
}