API reference

Complete a sync

Close the open sync. A full sync then marks every contact it did not receive as removed.

Request

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

Closes the open sync. A full sync then marks every contact it did not receive as removed. Always complete a sync, even when some records were rejected.

curl -X PATCH https://www.postaged.com/api/integrations/push/v1/sync \
  -H "Authorization: Bearer $POSTAGED_API_KEY" \
  -H "Idempotency-Key: 2026-10-03-complete-1" \
  -H "Content-Type: application/json" \
  -d '{
    "syncId": "0b6f3c3e-8d2a-4f7e-9a51-2c4d8e6f1a20"
  }'

const response = await fetch("https://www.postaged.com/api/integrations/push/v1/sync", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.POSTAGED_API_KEY}`,
    "Idempotency-Key": "2026-10-03-complete-1",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    syncId: "0b6f3c3e-8d2a-4f7e-9a51-2c4d8e6f1a20",
  }),
});
const result = await response.json();
console.log(result);

import os

import requests

response = requests.patch(
    "https://www.postaged.com/api/integrations/push/v1/sync",
    headers={
        "Authorization": f"Bearer {os.environ['POSTAGED_API_KEY']}",
        "Idempotency-Key": "2026-10-03-complete-1",
    },
    json={
        "syncId": "0b6f3c3e-8d2a-4f7e-9a51-2c4d8e6f1a20",
    },
    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

syncIdstringOptional
The open sync's id. When sent, it must name the open sync.

Request body

{
  "syncId": "0b6f3c3e-8d2a-4f7e-9a51-2c4d8e6f1a20"
}

Response 200

The sync is complete.

okboolean
Always true.
syncIdstring
modestring
One of full or delta.
recordsUpsertedinteger
recordsDeletedinteger
recordsRejectedinteger
markedRemovedinteger
Contacts a full sync marked as removed. A delta sync reports 0.

Response200 OK

{
  "ok": true,
  "syncId": "0b6f3c3e-8d2a-4f7e-9a51-2c4d8e6f1a20",
  "mode": "full",
  "recordsUpserted": 1998,
  "recordsDeleted": 0,
  "recordsRejected": 2,
  "markedRemoved": 14
}

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 complete the sync twice.	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	`no_open_sync`	There is no open sync to complete.	Begin a sync with POST /api/integrations/push/v1/sync first. A sync left open expires after 24 hours.
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 complete the sync twice."
  }
}

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."
  }
}

no_open_sync409

{
  "error": {
    "code": "no_open_sync",
    "message": "There is no open sync to complete."
  }
}

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."
  }
}