Programmatic social media posting: what changes vs. posting by hand

Concretely: a POST request with the post body, a list of connected profile IDs, and any media, sent with a stable idempotency key so the same logical request is safe to retry. That one call can target several platforms at once — the API fans it out to each platform's own publishing pipeline and hands back a single response.

A human clicking "schedule" does it once per post. Programmatic posting turns that into one endpoint with four modes instead of a separate integration for each: draft: true saves the post for review, an ISO 8601 scheduled_at fires it at a fixed instant, scheduled_at: "queue" drops it into the next open slot of a recurring schedule, and omitting both fields publishes immediately. A recurring cron or slot template expands into individually tracked posts ahead of a horizon, so "post every weekday at 9am" for two hundred customer accounts is one schedule resource per account, not two hundred timers someone has to babysit.

A person watching a platform's UI sees "posted" and moves on. Code needs something it can branch on. PostGate's create response is acceptance, not proof of publication — the aggregate post moves through draft or scheduled as waiting states, processing while at least one target is active, and lands on a terminal state of published, partial, failed, or canceled. The targets array is the operational truth underneath that: each platform destination carries its own status — pending, media_ready, publishing, and terminal outcomes of published, failed, or skipped, with awaiting_reconnect flagging a target that needs the customer to act. A partial result — some targets published, one didn't — is a normal, well-defined outcome your code can act on per target, not an ambiguous failure you have to guess about.

A human posting by hand almost never sees a rate limit — the platform's UI paces them naturally. Code sending hundreds of requests can hit one directly: PostGate surfaces this as a rate_limited error with retryable: true, meaning the same request can succeed later with backoff, not that something is broken. A session that would just prompt a human to log in again instead needs to be represented as data — profile_disconnected, or a target sitting in awaiting_reconnect — because nothing is going to click "reauthorize" on its own. Media a human would visually confirm before attaching instead gets probed asynchronously and can come back media_invalid, which needs a different asset rather than a retry. And every error PostGate returns carries a single stable code and a retryable flag, so a retry loop can decide by signal — retry only when told to, reuse the same idempotency key, back off with jitter — instead of pattern-matching on a message string that a provider can reword at any time.

None of these are exotic edge cases. They're the direct consequence of removing the human who used to absorb them silently — a rate limit the UI never let you hit, a login prompt that used to interrupt you instead of failing invisibly, a bad file you'd have caught by looking at it. This is also why webhook-driven completion matters more than polling once volume grows: subscribing to post.published, post.partial, and post.failed events lets your system react the moment delivery actually resolves, instead of a loop repeatedly asking "is it done yet" for thousands of posts in flight at once.