How to evaluate a social media publishing API
The first successful POST request proves almost nothing. A durable publishing API must preserve authority, prevent accidental duplicates, model provider differences, and tell you what happened after every delivery.
A social media publishing API is a service contract for creating, scheduling, delivering, and inspecting content across external platforms. The useful abstraction is not one universal “post” endpoint. It is a stable campaign and delivery model that preserves each provider’s fields, permissions, media rules, rate limits, and uncertain outcomes.
The API should own coordination, not pretend platforms are identical.
A unified publishing API creates leverage when it centralizes the work every integration needs: authentication boundaries, destination discovery, content preparation, media identity, scheduling, queueing, idempotency, receipts, and recovery. It becomes dangerous when it hides platform truth behind the smallest common payload.
For example, a WordPress post can be a draft, scheduled, pending, private, or published article with taxonomies and featured media. A Mastodon status can have visibility, content warnings, language, media, a future schedule, and an idempotency key. A Discord incoming webhook belongs to one channel and has its own message and attachment contract. A useful API can present one campaign above those differences without deleting them.
| Normalize | Keep provider-specific | Why |
|---|---|---|
| Campaign ID, workspace, source, schedule intent | Destination fields and media limits | The operator needs one work item without losing content fit. |
| Delivery states and attempt timestamps | Provider response, external ID, and URL | A shared status vocabulary still needs provider evidence. |
| Idempotency and request correlation | Provider-specific retry safety | Not every provider protects writes the same way. |
| Access scopes and workspace binding | Provider consent and account eligibility | Your API cannot grant a permission the destination did not grant. |
Seven contracts matter after the demo.
1. Destination discovery
Clients need a read-only way to discover channels, capabilities, connection state, availability, and safe defaults. Do not make an agent guess internal IDs or assume a connector shown in marketing is usable for its workspace.
2. Scoped authentication
Separate read, draft, media, connection, and publish authority. Bind every credential to the exact workspace and audience it is intended for. Provider credentials should remain inside the publishing service; callers should receive safe destination records, never reusable social account tokens.
3. Idempotent creation
A client will retry when a connection drops or its own process restarts. The API should require a stable idempotency key for create and publish operations, bind that key to the request fingerprint, and return the original result for an exact retry. Reusing the same key with a different payload should fail clearly.
Provider-level behavior still matters. Mastodon accepts an Idempotency-Key for status creation and documents a finite retention window. Other destinations may not provide equivalent protection, so the publishing service needs its own durable request and delivery records.
4. Media lifecycle
Large media should not travel through a general application server if direct object-storage upload is available. A safer flow initiates an upload, returns a short-lived signed destination, verifies size and type on completion, then exposes an immutable media ID. Publish payloads should reference that ID rather than a temporary URL or private storage key.
5. Preparation and approval
Preparation should be a non-public mutation: resolve source content, eligible destinations, exact variants, and media routing, then freeze them in a reviewable plan. A separate approval and consume step keeps “the system prepared a campaign” distinct from “an authorized human accepted this public delivery.”
6. Independent delivery states
One selected destination should become one delivery record. Campaign state can then be derived as scheduled, publishing, published, partial, failed, or canceled without flattening the underlying outcomes.
7. Reconciliation
The API must distinguish a known rejection from an unknown write outcome. If the provider may have accepted the post but the response was lost, do not automatically replay unless a provider idempotency mechanism or read-after-write check makes it safe. Hold the delivery for reconciliation and explain the next action.
A safe request flow separates preparation from publication.
- Discover: list the caller’s usable channels and ready media with read-only scopes.
- Prepare: submit a URL, Markdown, or inline source and choose explicit channel IDs or a bounded selector.
- Resolve: return the exact destination variants, settings, compatibility findings, and missing requirements.
- Freeze: create an immutable publish plan tied to the request fingerprint and idempotency key.
- Review: let an authorized workspace member inspect the exact public output and destination bindings.
- Consume: atomically create the campaign, delivery records, and approval receipt once.
- Observe: read campaign state, per-destination attempts, published URLs, and actionable failures.
The key design choice is a boundary: content preparation can be highly automated; public authority should be explicit, scoped, and observable.
A trusted internal service may legitimately use direct publishing. That should be a separate high-trust scope and configuration, not an accidental side effect of receiving ordinary write access.
Build or buy depends on where your advantage lives.
| Choose | When it fits | Cost you still own |
|---|---|---|
| Build provider integrations | Your product’s advantage depends on native platform behavior, unusual formats, or a small fixed set of destinations. | App review, token custody, policy changes, quotas, canaries, retries, and incident recovery. |
| Use a unified API | Your advantage is the workflow around publishing and you need several destinations quickly. | Vendor limits, data model fit, approval UX, operational visibility, and exit strategy. |
| Hybrid | A few strategic destinations need deep native support while the long tail needs a shared contract. | Two integration models and consistent status semantics. |
Count the lifecycle, not the endpoints. A connector is not finished when a test account publishes once. It also needs credential creation, validation, revocation, refresh, capability checks, rate controls, media handling, a production canary, monitoring, and a truthful availability state.
Questions that expose the real API
- Availability: Which connectors are generally usable, which are beta, and which require external platform approval?
- Ownership: Who creates the provider app, who owns its credentials, and where are tokens stored?
- Authority: Which scope can draft, prepare, approve, connect accounts, or publish directly?
- Isolation: How is every key, OAuth grant, plan, media object, and destination bound to one workspace?
- Retry safety: What happens after a timeout during a public write?
- Evidence: Does the response include destination state, attempt history, provider ID, and published URL when available?
- Media: Are uploads direct, immutable after completion, and validated against destination requirements?
- Change: How are breaking API changes versioned and provider deprecations communicated?
- Limits: Are platform limits, vendor quotas, and billing units distinct and visible?
How the PostOnce.co API is positioned
PostOnce.co exposes the same content, channel, media, publish-plan, and delivery model through REST, a repository CLI, local MCP, and hosted MCP. The current public contract favors browser-reviewed publish plans for ordinary agents and reserves direct publication for a separate high-trust scope.
Its best fit is a developer or operator who wants social, community, email, and owned-content destinations under one contract and values destination-level receipts. It is not a substitute for a connector whose status is still Beta or Approval required, and it does not make external provider reviews or account eligibility disappear.
Read the concrete endpoints and scope model on the API and MCP page, verify current connector states on Platforms, and confirm which plans include API access on Pricing.
How should you compare publishing API costs?
Count the successful destinations, not just the source campaigns. Twenty campaigns delivered to five accounts create one hundred destination deliveries. Then compare connected-account limits, stored media, API access, and the provider fees your integration needs.
Use PostOnce’s workload calculator to check the lowest listed plan for your inputs. Paid Pro and Agency include API and MCP access; the card-free trial covers the core dashboard workflow. A subscription does not remove a platform’s own approval or eligibility requirements.
How do you test recovery before committing to an API?
Ask how the product distinguishes a rejected request from a missing response after a write. Inspect a partial campaign and confirm that recovering one destination does not resend successful destinations. The scheduled-post recovery guide describes the operator decisions your integration should preserve.
Primary sources
- RFC 9700: Best Current Practice for OAuth 2.0 Security — current OAuth security guidance, including redirect, PKCE, and token protections.
- Model Context Protocol authorization specification — OAuth-based authorization, issuer validation, client registration priorities, and resource-server discovery for HTTP MCP transports.
- Mastodon API: statuses — provider-level creation, scheduling, fields, and idempotency behavior.
- WordPress REST API: Posts — the richer article fields a universal caption model would lose.
- Discord developer documentation: webhooks — channel-bound incoming webhook behavior.