Approval-aware publishing, from scripts or AI assistants.

Version 1

REST endpoints

Base URL https://plansend.io/api/v1. Send and receive JSON; responses arrive under a data key, errors as { "error": { "code", "message" } } with a matching HTTP status. Writes that change a post require the current revision, so two people can never overwrite each other unknowingly.

Reference

Requests and responses

The post lifecycle in four calls. Ids, tokens and dates are illustrative; scheduled_at and run_at are UTC, local_datetime and timezone are what you sent.

curl https://plansend.io/api/v1/posts \
  -H "Authorization: Bearer $PLANSEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Launch week",
    "body": "Ready to review.",
    "channel_ids": [12, 15]
  }'

{
  "data": {
    "id": 481, "status": "draft", "revision": 1, "approved_revision": null,
    "title": "Launch week", "body": "Ready to review.",
    "scheduled_at": null, "local_datetime": null, "timezone": null,
    "variants": [
      { "id": 901, "channel_id": 12, "network": "linkedin", "channel_name": "Acme LinkedIn", "status": "draft" },
      { "id": 902, "channel_id": 15, "network": "instagram", "channel_name": "@acme", "status": "draft" }
    ],
    "media": []
  }
}

curl -X POST https://plansend.io/api/v1/posts/481/request-approval \
  -H "Authorization: Bearer $PLANSEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reviewer_email": "[email protected]",
    "passcode": "spring-24"
  }'

{
  "data": {
    "review_url": "https://plansend.io/review/9f1c…Xw",
    "expires_at": "2026-09-16T09:00:00.000Z",
    "emailed": true
  }
}

curl -X POST https://plansend.io/api/v1/posts/481/approve \
  -H "Authorization: Bearer $PLANSEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{"revision": 1, "note": "Approved on the call"}'

curl -X POST https://plansend.io/api/v1/posts/481/schedule \
  -H "Authorization: Bearer $PLANSEND_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "revision": 1,
    "local_datetime": "2026-09-15T09:30",
    "timezone": "Europe/Lisbon"
  }'

{
  "data": {
    "id": 481, "status": "scheduled",
    "revision": 1, "approved_revision": 1,
    "scheduled_at": "2026-09-15 08:30:00",
    "local_datetime": "2026-09-15T09:30",
    "timezone": "Europe/Lisbon",
    "variants": [ … ], "media": []
  }
}

curl https://plansend.io/api/v1/jobs \
  -H "Authorization: Bearer $PLANSEND_KEY"

{
  "data": [
    {
      "id": 77, "post_id": 481, "variant_id": 901, "revision": 1,
      "status": "published", "attempts": 1,
      "run_at": "2026-09-15 08:30:00",
      "external_url": "https://www.linkedin.com/feed/update/…",
      "last_error": null,
      "idempotency_key": "post:481:variant:901:revision:1"
    }
  ]
}

Outbound events

Signed webhooks with automatic retries

Create an endpoint under Developers → Webhooks and subscribe it to post.published, post.failed, post.approved or channel.disconnected. Each endpoint receives its own whsec_… signing secret once. Deliveries retry after about 1, 5 and 30 minutes, then remain visible as failed in the delivery history.

Verify PlanSend-Signature before parsing the JSON. Read PlanSend-Timestamp, concatenate it with a period and the exact raw request body, compute HMAC-SHA256 with the endpoint secret, and compare the hexadecimal digest to the value after v1=. Reject old timestamps to prevent replay.

const expected = crypto
  .createHmac('sha256', process.env.PLANSEND_WEBHOOK_SECRET)
  .update(`${req.get('PlanSend-Timestamp')}.${req.rawBody}`)
  .digest('hex');

const supplied = req.get('PlanSend-Signature').replace('v1=', '');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(supplied))) throw new Error('Invalid signature');

Errors

One shape, meaningful codes

Every error is { "error": { "code": "…", "message": "…" } } with an HTTP status you can branch on. code is stable; message is for people. MCP tools return the same codes inside a tool error (see below).

Model Context Protocol

Connect an AI assistant

The MCP server at https://plansend.io/mcp exposes PlanSend as tools over Streamable HTTP: list channels, create drafts, request approval, approve a revision, schedule, inspect jobs and draft copy with AI Assist. It authenticates with the same API keys, and scopes, revision checks and the audit log apply exactly as they do for the REST API. An assistant can prepare a week of posts, but every post still goes through the review and scheduling rules; nothing is published on the spot.

1. Create an API key under Developers → API keys. Use read scope for an assistant that only reports, write scope for one that drafts and schedules.
2. Add the server to your client with one of the snippets below, replacing YOUR_KEY.
3. Ask: “List my channels”, “Draft three LinkedIn posts about the launch and send them for approval”, “What is scheduled next week?”

claude mcp add --transport http plansend https://plansend.io/mcp --header "Authorization: Bearer YOUR_KEY"

{
  "mcpServers": {
    "plansend": {
      "url": "https://plansend.io/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "plansend": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://plansend.io/mcp", "--header", "Authorization: Bearer YOUR_KEY"]
    }
  }
}
# the same bridge from a terminal:
# npx mcp-remote https://plansend.io/mcp --header "Authorization: Bearer YOUR_KEY"

curl https://plansend.io/mcp \
  -H "Authorization: Bearer $PLANSEND_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"list_channels","arguments":{}}}'

MCP tools

What the assistant can do

Each tool describes its arguments to the client, so the assistant fills them in itself. Results carry the same JSON as the REST data payload in the first text block and a one-sentence summary in the second. Failures come back as a tool error with { "error": code, "message": text } using the codes above, so a stale revision or a missing approval is explained rather than crashing the conversation.

Two resources are readable as well: plansend://posts/{postId} (the same object as get_post) and plansend://calendar/{from}/{to} for scheduled posts in an inclusive YYYY-MM-DD range. There is deliberately no “publish now” tool: publishing happens through scheduling, in the worker, with the idempotency guarantees below.