PostSail examples

Examples for the PostSail publishing API: one HTTPS request posts a text or a short video to several social accounts and reports the result on each account.

• What works today: X and Bluesky.
• In review: YouTube Shorts and TikTok. They open when Google's and TikTok's app reviews finish.
• Coming: LinkedIn soon; Instagram, Facebook and Threads later.

This repository has:

• examples/curl, examples/node and examples/python: the same five flows in each language (list accounts, dry run, post to X and Bluesky, read a post, schedule a post).
• mcp: an MCP server, so an AI assistant can draft and check posts through PostSail. It publishes only when you allow it in its configuration, and every post must first pass a dry run of the same content.

Full API docs: postsail.app/docs. OpenAPI 3.1 file: https://postsail.app/api/v1/openapi.json.

Before you start

1. Create a workspace at postsail.app/app. Both plans have a 7-day free trial; a card is required and nothing is charged until the trial ends.

2. In the dashboard, open API and create a key.

   • To try things safely, use the sandbox account. Every workspace has one: posts to it go nowhere, but they run through the real queue, checks and retries. Dry runs and sandbox posts do not count against your plan.
   • For real posting, prefer a key limited to the accounts it needs.

3. Keep the key in an environment variable and never commit it:

   export POSTSAIL_API_KEY="..."   # from the dashboard; shown once
   

Quick start

curl -X POST https://postsail.app/api/v1/posts \
  -H "Authorization: Bearer $POSTSAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dry_run": true, "targets": [{"account": "sandbox", "text": "Hello from the PostSail API"}]}'

A dry run runs every check (media, platform rules, blocked words) and stores what would be sent, without calling any platform. Remove "dry_run": true to publish.

Run the examples

./examples/curl/dry-run.sh                      # curl
node examples/node/dry-run.mjs                  # Node.js 18+
pip install -r examples/python/requirements.txt
python examples/python/dry_run.py               # Python 3.9+

Each folder has the same five scripts: list accounts, dry run, post to X and Bluesky (a dry run unless you add --publish), read a post, schedule a post. The MCP server's setup is in mcp/README.md.

Good to know

• No duplicates. Send an Idempotency-Key header or an external_id; a repeated request never creates a second post. A dry run with an external_id reserves it too, so give the real post its own external_id (the examples send one only when publishing).
• Links on X. X charges more for posts that contain a link, so PostSail removes links from the main X text. Put the link in first_comment: it is posted as a reply.
• Scheduling. publish_at (ISO 8601) up to 30 days ahead; publish_before drops the post instead of publishing it late.

Security

• The examples read the key only from POSTSAIL_API_KEY and send it only to https://postsail.app/api.
• If a key leaks, revoke it in the dashboard (API > Revoke) and create a new one.
• Report a security problem: see SECURITY.md.

License

MIT, see LICENSE.