API reference

Read the open sync

Read the open sync's progress, or null when none is open.

Request

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

The open sync's progress, or null when none is open.

curl https://www.postaged.com/api/integrations/push/v1/sync \
  -H "Authorization: Bearer $POSTAGED_API_KEY"

const response = await fetch("https://www.postaged.com/api/integrations/push/v1/sync", {
  headers: {
    Authorization: `Bearer ${process.env.POSTAGED_API_KEY}`,
  },
});
const result = await response.json();
console.log(result);

import os

import requests

response = requests.get(
    "https://www.postaged.com/api/integrations/push/v1/sync",
    headers={"Authorization": f"Bearer {os.environ['POSTAGED_API_KEY']}"},
    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

Response 200

The open sync, or null.

syncnull or object
- idstring
- modestring
  One of full or delta.
- statusstring
- expiresAtstring
- batchesReceivedinteger
- recordsUpsertedinteger
- recordsDeletedinteger
- recordsRejectedinteger

Response200 OK

{
  "sync": {
    "id": "0b6f3c3e-8d2a-4f7e-9a51-2c4d8e6f1a20",
    "mode": "full",
    "status": "open",
    "expiresAt": "2026-10-04T14:05:00.000Z",
    "batchesReceived": 2,
    "recordsUpserted": 1998,
    "recordsDeleted": 0,
    "recordsRejected": 2
  }
}

Response200 OK

{
  "sync": null
}

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

rate_limited429

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

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