API reference

Integrations push API

Push contacts from a custom CRM into a Postaged integration, one sync at a time.

Base URL and authentication

Every operation is under https://www.postaged.com/api/integrations/push/v1 and sends and receives JSON over HTTPS.

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

Operations

Operation	Method	Path
Inspect the integration	GET	`/api/integrations/push/v1`
Read the schema	GET	`/api/integrations/push/v1/schema`
Declare the schema	POST	`/api/integrations/push/v1/schema`
Read the open sync	GET	`/api/integrations/push/v1/sync`
Begin a sync	POST	`/api/integrations/push/v1/sync`
Complete a sync	PATCH	`/api/integrations/push/v1/sync`
Push records	POST	`/api/integrations/push/v1/records`
List sync rejections	GET	`/api/integrations/push/v1/sync/rejections`

How a sync works

Declare the schema: the fields you will push, with their types.
Begin a sync: full when you send every contact, delta for a small follow-up change. One sync can be open at a time.
Push records in batches of up to 1,000 records, until every contact is sent.
Complete the sync, even when some records were rejected. A full sync then marks every contact it did not receive as removed.

Check records first with ?validate=1, which writes nothing. Build a daily CRM sync walks through the whole job.

Errors

Errors use the body { "error": { "code", "message", "details" } }; details appears only on some codes. Every operation can return these three; each operation page lists the rest. 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."
  }
}

Limits

1,000 records and 4.25 MB per batch, and 64 KB per record.
1,000 declared fields.
external_id up to 128 characters, and Idempotency-Key up to 200 characters.
An unfinished sync expires after 24 hours.
Rejection pages hold 1 to 1,000 items, 100 by default.
About 120 requests per minute per source IP, counted together with the Integrations MCP server. Over the limit: 429 rate_limited with Retry-After: 60.