# Postproxy - Unified API for Social Media Publishing, Comments, DMs, and Reviews

> Website: https://postproxy.dev
> API: https://api.postproxy.dev
> App: https://app.postproxy.dev
> GitHub: https://github.com/postproxy

Postproxy is a unified social media API for the full lifecycle: publish content, then manage comments, direct messages, and location-based reviews through one contract.

We are built for production systems, not demos:
- Official platform APIs and approved OAuth scopes only (no scraping, no risky unofficial automation)
- Reliability-first execution with retries, per-platform states, and clear failure reporting
- Infrastructure and compliance posture designed for serious teams
- Human support that helps you ship and keep pipelines healthy

## What Postproxy Does

Postproxy replaces per-platform logic with one API layer that handles:
- Platform-specific endpoints, media rules, and validation
- OAuth token handling and refresh
- Publish execution, retries, and per-platform status visibility
- Engagement workflows (comments, DMs, reviews)

Integrate once, keep one payload shape, and let Postproxy absorb platform differences.

For AI agent pipelines, Postproxy provides a native MCP server with tools for the full social workflow — publishing, comments, DMs, queues, and stats — so agents can execute end-to-end without building per-platform integrations.

## Reliability, Trust & Official APIs

- Infrastructure: European hosting and operations
- Security: encryption in transit/at rest, strict access controls
- Compliance: GDPR-compliant; SOC 2 Type II certification in progress
- Officialness: only official APIs and approved auth flows
- Support: community, standard, priority, and enterprise support paths

## How It Works

1. Create account and API key
2. Connect social profiles in profile groups
3. Send posts, comments, DMs, and review replies via API
4. Track outcomes via statuses and webhooks

## Core Concepts

**Profile** - Connected social account (or account container) on a platform.

**Profile Group** - Logical workspace for profiles, credentials, and access scope.

**Post** - Content unit published to one or more profiles.

**Comment** - Engagement object on a post (or profile-scoped review for Google Business).

**Chat / Message** - 1:1 direct messaging entities (DM conversation and messages).

**Queue** - Recurring publishing schedule with timeslots, priorities, and jitter.

**Placement** - Platform destination target (for example Facebook Page, LinkedIn org, Pinterest board, Google location).

## Supported Platforms

| Platform | Platform ID | Formats |
|----------|-------------|---------|
| Facebook | `facebook` | `post`, `reel`, `story` |
| Instagram | `instagram` | `post`, `reel`, `story` |
| TikTok | `tiktok` | `video`, `image` |
| LinkedIn | `linkedin` | `post` |
| YouTube | `youtube` | `post` |
| X (Twitter) | `twitter` | `post`, `poll` |
| Threads | `threads` | `post` |
| Pinterest | `pinterest` | `pin` |
| Bluesky | `bluesky` | `post` |
| Telegram | `telegram` | `post` (channel) |
| Google Business | `google_business` | `standard`, `event`, `offer`, `photo` |

## Authentication

All requests use Bearer auth:

```
Authorization: Bearer YOUR_API_KEY
```

API key types:
- Full Access - all profile groups + profile-group management
- Profile Group Scoped - only one profile group

Profile group context can come from:
1. `?profile_group_id=<id>`
2. key scope
3. default group (full-access keys)

## Quickstart

### List profiles

```bash
curl -X GET "https://api.postproxy.dev/api/profiles"   -H "Authorization: Bearer YOUR_API_KEY"
```

### Create post

```bash
curl -X POST "https://api.postproxy.dev/api/posts"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{
    "post": {"body": "Hello world"},
    "profiles": ["facebook", "instagram"],
    "media": ["https://example.com/image.jpg"]
  }'
```

## API Reference

Base URL: `https://api.postproxy.dev`

### Response Format

Single resource:
```json
{ "id": "abc123", "name": "My Resource" }
```

Collection:
```json
{ "total": 120, "page": 0, "per_page": 10, "data": [] }
```

### Common Errors

| Code | Response shape |
|------|----------------|
| `400` | `{"status":400,"error":"Bad Request","message":"..."}` |
| `401` | `{"error":"Invalid API key"}` |
| `404` | `{"error":"Not found"}` |
| `405` | `{"error":"Unsupported method for <platform>"}` |
| `422` | `{"error":"..."}` or `{"errors":["..."]}` |

### Pagination

| Parameter | Type | Default |
|-----------|------|---------|
| `page` | integer | `0` |
| `per_page` | integer | `10` |

## Posts API

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/posts` | List posts |
| `GET` | `/api/posts/:id` | Get post |
| `GET` | `/api/posts/stats` | Post stats snapshots |
| `POST` | `/api/posts` | Create post |
| `PATCH` | `/api/posts/:id` | Update post |
| `POST` | `/api/posts/:id/publish` | Publish draft |
| `POST` | `/api/posts/:id/delete_on_platform` | Delete on selected platform(s) |
| `DELETE` | `/api/posts/:id` | Delete from Postproxy DB |

Create/update highlights:
- `profiles`: profile ids or platform ids
- `media`: URL, multipart file, base64/data-uri shapes
- `platforms`: per-platform params
- `thread`: follow-up posts for chains (X, Threads, Bluesky)
- `queue_id` + `queue_priority`: queue scheduling
- drafts, scheduling, and profile-group scoping supported

Threading:
- Supported on X, Threads, Bluesky
- Children publish sequentially inside each platform chain
- Chains run independently per platform

X Polls:
- `platforms.twitter.format = "poll"`
- `poll_options`: 2-4 options (max 25 chars each)
- `poll_duration_minutes`: 5..10080
- Polls cannot include media and cannot be threaded

Delete-on-platform support:
- Facebook, Threads, X, LinkedIn, Pinterest, YouTube

Post statuses:
- Post-level: `draft`, `processing`, `processed`, `scheduled`
- Platform-level: `processing`, `published`, `failed`, `failed_waiting_for_retry`, `deleted`

## Comments API (post-level)

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/posts/:post_id/comments` | List comments |
| `GET` | `/api/posts/:post_id/comments/:id` | Get comment |
| `POST` | `/api/posts/:post_id/comments` | Create comment/reply |
| `DELETE` | `/api/posts/:post_id/comments/:id` | Delete comment |
| `POST` | `/api/posts/:post_id/comments/:id/hide` | Hide comment |
| `POST` | `/api/posts/:post_id/comments/:id/unhide` | Unhide comment |
| `POST` | `/api/posts/:post_id/comments/:id/like` | Like comment |
| `POST` | `/api/posts/:post_id/comments/:id/unlike` | Unlike comment |

All endpoints require `profile_id` query parameter.

Support matrix:

| Action | Instagram | Facebook | Threads | Bluesky | YouTube | LinkedIn |
|--------|-----------|----------|---------|---------|---------|----------|
| List | Yes | Yes | Yes | Yes | Coming soon | Coming soon |
| Reply | Yes | Yes | Yes | No | Coming soon | Coming soon |
| Delete | Yes | Yes | No | No | Coming soon | Coming soon |
| Hide/Unhide | Yes | Yes | Yes | No | Coming soon | Coming soon |
| Like/Unlike | No | Yes | No | No | Coming soon | Coming soon |

Notes:
- Unsupported actions return `405`
- Write operations are async (`pending` -> `published`/`failed`)
- Google Business reviews are profile-scoped, use Profile Comments API

## Direct Messages API

DMs are supported on Facebook Messenger, Instagram, Telegram, and Bluesky.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/profiles/:profile_id/chats` | List chats |
| `POST` | `/api/profiles/:profile_id/chats` | Find/create chat |
| `GET` | `/api/chats/:id` | Get chat |
| `GET` | `/api/chats/:chat_id/messages` | List messages |
| `POST` | `/api/chats/:chat_id/messages` | Send message |
| `GET` | `/api/messages/:id` | Get message |
| `PATCH` | `/api/messages/:id` | Edit outbound message (Telegram) |
| `POST` | `/api/messages/:id/react` | React to message (FB/IG) |
| `DELETE` | `/api/messages/:id/unreact` | Remove reaction |
| `POST` | `/api/chats/:id/archive` | Archive chat (Bluesky) |
| `DELETE` | `/api/chats/:id/archive` | Unarchive chat (Bluesky) |
| `POST` | `/api/posts/:post_id/comments/:id/private_reply` | DM comment author (FB/IG) |
| `GET/POST/DELETE` | `/api/profiles/:id/ice_breakers` | Instagram ice breakers |

Capability matrix:

| Capability | Facebook | Instagram | Telegram | Bluesky |
|------------|----------|-----------|----------|---------|
| Text send/receive | Yes | Yes | Yes | Yes |
| Attachments | Yes | Yes | Yes | No |
| Reactions | Yes | Yes | No | No |
| Edit outbound | No | No | Yes | No |
| Delivery/read receipts | Yes | Yes | No | No |
| Archive chat | No | No | No | Yes |
| Private reply to comment | Yes | Yes | No | No |
| Ice breakers | No | Yes | No | No |
| ig.me / m.me referrals | Yes | Yes | No | No |

Messaging window:
- Meta (Facebook/Instagram): 24h from last inbound user message
- ig.me/m.me referral also opens 24h window
- Telegram: no 24h window, but user must DM bot first
- Bluesky: no 24h window; recipient DM preferences apply

Message statuses:
- outbound: `pending`, `published`, `failed_waiting_for_retry`, `failed`
- inbound: `received`

Send message example:

```bash
curl -X POST "https://api.postproxy.dev/api/chats/CHAT_ID/messages"   -H "Authorization: Bearer YOUR_API_KEY"   -H "Content-Type: application/json"   -d '{"body":"Thanks for reaching out"}'
```

## Profile Comments API (Google Business reviews)

Profile comments are comments that belong to a profile/location (not a post). Currently this API is for Google Business reviews.

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/profiles/:profile_id/comments` | List profile comments |
| `GET` | `/api/profiles/:profile_id/comments/:id` | Get profile comment |
| `POST` | `/api/profiles/:profile_id/comments` | Reply to review |
| `DELETE` | `/api/profiles/:profile_id/comments/:id` | Delete your reply |

Key behaviors:
- `placement_id` filters by location (`accounts/X/locations/Y`)
- Multi-location accounts without `placement_id` return mixed location reviews
- Top-level reviews are synced from Google; API writes are replies only (`parent_id` required)
- Sync runs twice daily (06:00 and 18:00 UTC)
- `permalink` points to location reviews page

## Queues API

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/post_queues` | List queues |
| `GET` | `/api/post_queues/:id` | Get queue |
| `GET` | `/api/post_queues/:id/next_slot` | Next available slot |
| `POST` | `/api/post_queues` | Create queue |
| `PATCH` | `/api/post_queues/:id` | Update queue |
| `DELETE` | `/api/post_queues/:id` | Delete queue |

Queue concepts:
- Timeslots: weekly `day` (0-6) + `time` (`HH:MM`) in queue timezone
- Priority: `high`, `medium`, `low`
- Jitter: random shift 0-60 min
- Pause via `enabled: false`
- Rearrangement happens automatically when inputs change

To queue a post, pass `queue_id` and optional `queue_priority` in `POST /api/posts`.

## Profiles API

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/profiles` | List profiles |
| `GET` | `/api/profiles/:id` | Get profile |
| `GET` | `/api/profiles/:id/placements` | List placements |
| `DELETE` | `/api/profiles/:id` | Disconnect profile |

Placements are relevant for platforms like Facebook pages, LinkedIn organizations, Pinterest boards, and Google Business locations.

## Profile Groups API

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/profile_groups` | List profile groups |
| `GET` | `/api/profile_groups/:id` | Get profile group |
| `POST` | `/api/profile_groups` | Create profile group |
| `DELETE` | `/api/profile_groups/:id` | Delete profile group |
| `POST` | `/api/profile_groups/:id/initialize_connection` | Create OAuth connect URL |

## Webhooks

Subscribe to all events (`*`) or specific event types.

Event types:
- Posts: `post.processed`, `post.imported`, `platform_post.published`, `platform_post.failed`, `platform_post.failed_waiting_for_retry`, `platform_post.insights`
- Post comments: `comment.created`, `comment.failed`, `comment.failed_waiting_for_retry`
- Profile comments: `profile_comment.created`, `profile_comment.failed`, `profile_comment.failed_waiting_for_retry`
- DMs: `message.received`, `message.sent`, `message.delivered`, `message.read`, `message.edited`, `message.deleted`, `message.failed_waiting_for_retry`, `message.failed`
- DM reactions/referrals: `reaction.received`, `referral.received`

## Platform-Specific Parameters (high-level)

### Facebook (`facebook`)
- Formats: `post`, `reel`, `story`
- Common params: `format`, `first_comment`, `page_id`
- Comments + DMs supported

### Instagram (`instagram`)
- Formats: `post`, `reel`, `story`
- Reel params include `cover_url`, `thumb_offset`, collaborators, optional trial strategy
- Comments + DMs + ice breakers + private reply supported

### TikTok (`tiktok`)
- Formats: `video`, `image`
- Params include privacy and interaction toggles (`disable_comment`, `disable_duet`, `disable_stitch`)
- No comments API, no DMs API

### LinkedIn (`linkedin`)
- Format: `post`
- Param: `organization_id`
- Comments support coming soon; no DMs API

### YouTube (`youtube`)
- Format: `post` (channel video)
- Params: `title`, `privacy_status`, optional `cover_url`

### X (Twitter) (`twitter`)
- Formats: `post`, `poll`
- Poll params: `poll_options`, `poll_duration_minutes`
- Supports post chains (threads)

### Threads (`threads`)
- Format: `post`
- Supports post chains
- Post comments supported (list/reply/hide)

### Pinterest (`pinterest`)
- Format: `pin`
- Params: `title`, `board_id` (required), `destination_link`, video cover params

### Bluesky (`bluesky`)
- Format: `post`
- Supports post chains and DM text
- Comments are list-only (read), DMs are text-only, archive/unarchive chat supported

### Telegram (`telegram`)
- Format: `post` (channel publishing)
- Params: `parse_mode`, `disable_link_preview`, `disable_notification`
- DMs supported; supports `reply_markup` and outbound edit via DM API

### Google Business (`google_business`)
- Formats: `standard`, `event`, `offer`, `photo`
- Key params: `location_id`, `cta_action_type`, `cta_url`, event/offer date fields
- Reviews and replies handled via Profile Comments API

## Calendar API (public, no auth)

`GET /api/calendar` exposes social dates (holidays, awareness, sensitive/no-post windows) with filters for category, type, country, tags, month, and date range.

## Automation & Workflow Integrations

Postproxy is designed for automation-first teams. Use one reliable execution layer behind your orchestrators and agents.

Available integrations:
- MCP - Native MCP server for AI agents (see below)
- OpenClaw - ClawHub skill for personal AI assistant workflows
- n8n - Verified node
- Needle - Official connector
- Make - Official app
- Zapier - Verified app

Typical scenarios:
- CMS -> social auto-publishing
- AI-generated content -> human approval -> publish
- Multi-brand routing and per-account outcomes
- Event-driven publishing from product/backend events
- Support and engagement automations (comments, DMs, reviews)

## MCP Server (AI Agents)

Postproxy exposes the **full social workflow as native MCP capabilities** — not just publishing. Agents get everything they need to run end-to-end pipelines: publish content, manage queues, moderate and reply to comments, read and send DMs, check stats, and track outcomes — all through one stable tool surface.

Works with Claude Code, Cursor, and any MCP-compatible client. Two deployment options:
- **Hosted remote MCP** (zero install): `https://mcp.postproxy.dev/mcp?api_key=YOUR_KEY` (or `X-Postproxy-API-Key` header)
- **Local npm package**: `npm install -g postproxy-mcp` with stdio transport

Why MCP + Postproxy for agent pipelines:
- One contract for 11 platforms — agents reason about intent, Postproxy handles platform rules
- Full lifecycle coverage: publish -> engage -> measure, not publish-only
- Observable execution: per-platform status, retries, and history instead of fire-and-forget
- Safe agent controls: `require_confirmation` (dry run), `draft`, `schedule`, `idempotency_key`
- Official APIs underneath — agents never touch scraping or unofficial automation

### MCP tool categories

| Category | Tools |
|----------|-------|
| Auth & workspace | `auth_status`, `profile_groups_list` |
| Profiles & placements | `profiles_list`, `profiles_placements`, `profiles_stats` |
| Publishing | `post_publish`, `post_update`, `post_publish_draft`, `post_status`, `post_delete`, `post_delete_on_platform`, `post_stats`, `history_list` |
| Queues | `queues_list`, `queues_get`, `queues_create`, `queues_update`, `queues_delete`, `queues_next_slot` |
| Comments | `comments_list`, `comments_get`, `comments_create`, `comments_delete`, `comments_hide`, `comments_unhide`, `comments_like`, `comments_unlike` |
| Direct messages | `dm_chats_list`, `dm_chat_create`, `dm_chat_get`, `dm_messages_list`, `dm_message_send`, `dm_message_get`, `dm_message_edit`, `dm_message_react`, `dm_message_unreact`, `dm_chat_archive`, `dm_chat_unarchive`, `dm_comment_private_reply` |

`post_publish` supports: multi-profile targets, media URLs or local files, platform-specific params, post chains (`thread`), queue assignment (`queue_id` + `queue_priority`), scheduling, and drafts.

### Agent pipeline examples

- **Release notes -> social**: agent reads changelog, drafts posts per platform, publishes with `require_confirmation` for human approval
- **Comment moderation**: agent lists incoming comments, generates replies, posts them back via `comments_create`
- **DM inbox automation**: agent reads chats (`dm_chats_list` / `dm_messages_list`), routes by intent, sends replies (`dm_message_send`) or private-replies to commenters (`dm_comment_private_reply`)
- **Content calendar**: agent creates queues with timeslots, adds posts with priority, checks next slot
- **Deploy summaries**: agent turns recent PRs/commits into publishable updates across accounts
- **Multi-brand routing**: agent lists profile groups, picks targets per brand, publishes with per-platform outcomes

### Quick setup

Remote (Claude Code):
```bash
claude mcp add --transport http postproxy \
  https://mcp.postproxy.dev/mcp?api_key=YOUR_KEY
```

Local:
```bash
npm install -g postproxy-mcp
claude mcp add --transport stdio postproxy-mcp \
  --env POSTPROXY_API_KEY=your-api-key \
  --env POSTPROXY_BASE_URL=https://api.postproxy.dev/api \
  -- postproxy-mcp
```

Docs: https://postproxy.dev/automation/mcp-server/
GitHub: https://github.com/postproxy/postproxy-mcp

## SDKs

Official SDKs available for: Node/TypeScript, Python, Go, Ruby, PHP, Java, .NET.

## Pricing

All plans include API access, SDKs, scheduling, and platform coverage.

| Plan | Price | Profile Groups | Posts/mo | Publish Logs | Webhooks | Support |
|------|-------|----------------|----------|--------------|----------|---------|
| Free | $0/mo | 2 | 10 | No | No | Community |
| Starter | $17/mo ($12 annual) | 10 | 120 | 30 days | Yes | Standard |
| Scale | $49/mo ($35 annual) | 50 | Unlimited | 180 days | Yes | Priority |
| Enterprise | $399/mo ($299 annual) | Unlimited | Unlimited | Unlimited | Yes | Enterprise |

1 publish to 1 platform = 1 post. Retries do not consume extra quota.

## About

Postproxy is built by a team that has already run high-load social integrations in production. The product is optimized for reliability and operational clarity under real-world API constraints, not idealized platform docs.

If your team needs help with integration details, platform edge-cases, or rollout architecture, support is part of the product experience.

## Getting Started

- [Website](https://postproxy.dev): Product overview and entry point
- [App / Sign up](https://app.postproxy.dev/users/sign_up): Create an account and API key
- [API Base URL](https://api.postproxy.dev): Root for all API requests
- [Quickstart](https://postproxy.dev/getting-started/quickstart/): First request in minutes
- [SDKs](https://postproxy.dev/getting-started/sdks/): Official client libraries

## API Reference

- [Overview](https://postproxy.dev/reference/overview/): Auth, formats, and conventions
- [Posts](https://postproxy.dev/reference/posts/): Publish and manage content
- [Comments](https://postproxy.dev/reference/comments/): Post-level engagement
- [Direct Messages](https://postproxy.dev/reference/direct-messages/): 1:1 conversations
- [Profile Comments](https://postproxy.dev/reference/profile-comments/): Google Business reviews
- [Queues](https://postproxy.dev/reference/queues/): Recurring publishing schedules
- [Profiles](https://postproxy.dev/reference/profiles/): Connected social accounts
- [Profile Groups](https://postproxy.dev/reference/profile-groups/): Workspaces and access scope
- [Webhooks](https://postproxy.dev/reference/webhooks/): Event notifications
- [Platforms](https://postproxy.dev/reference/platforms/): Per-platform capabilities
- [Calendar](https://postproxy.dev/reference/calendar/): Public calendar endpoints

## Platform Details

- [Facebook](https://postproxy.dev/reference/platforms/facebook/): Facebook Pages support
- [Instagram](https://postproxy.dev/reference/platforms/instagram/): Instagram support
- [TikTok](https://postproxy.dev/reference/platforms/tiktok/): TikTok support
- [X (Twitter)](https://postproxy.dev/reference/platforms/twitter/): X / Twitter support
- [Threads](https://postproxy.dev/reference/platforms/threads/): Threads support
- [LinkedIn](https://postproxy.dev/reference/platforms/linkedin/): LinkedIn support
- [YouTube](https://postproxy.dev/reference/platforms/youtube/): YouTube support
- [Pinterest](https://postproxy.dev/reference/platforms/pinterest/): Pinterest support
- [Bluesky](https://postproxy.dev/reference/platforms/bluesky/): Bluesky support
- [Telegram](https://postproxy.dev/reference/platforms/telegram/): Telegram support
- [Google Business](https://postproxy.dev/reference/platforms/google-business/): Google Business Profile support

## Automation & Integrations

- [Calendar](https://postproxy.dev/calendar): Content calendar
- [Automation](https://postproxy.dev/automation): Automation overview
- [MCP](https://postproxy.dev/automation/mcp): MCP server for AI agents
- [MCP Docs](https://postproxy.dev/automation/mcp-server/): MCP setup and tools
- [OpenClaw](https://postproxy.dev/automation/openclaw): OpenClaw integration
- [n8n](https://postproxy.dev/automation/n8n): n8n integration
- [Needle](https://postproxy.dev/automation/needle): Needle integration
- [Make](https://postproxy.dev/automation/make): Make integration
- [Zapier](https://postproxy.dev/automation/zapier): Zapier integration

## More

- [Pricing](https://postproxy.dev/pricing): Plans and limits
- [About](https://postproxy.dev/about): Company and contact
- [GitHub Org](https://github.com/postproxy): Open-source repositories
- [MCP GitHub](https://github.com/postproxy/postproxy-mcp): MCP server source
- [Skills Repo](https://github.com/postproxy/awesome-marketing-skills): Marketing automation skills