# crosspost: announce new posts on four networks safely

[crosspost](https://github.com/IndianOpinion/crosspost) is a WordPress plugin for publishers. When a post is published for the first time, it posts a short announcement to X, Threads, Bluesky and Mastodon through their official APIs, using the site owner's own credentials. It is MIT licensed, and v0.1.0 was released on 19 November 2026.

It was written from scratch from an idea, as part of a set of utilities built between 11 and 19 November 2026 by language-model coding agents under the editor's direction. It has not run on a live site.

## The problem

A publisher either announces each article by hand, which is slow and forgotten at night, or wires up an "on publish, call the API" hook. The naive hook goes wrong in predictable ways.

- It fires on every save of a published post, so a typo fix posts the article again.

- It fires for imports and bulk status changes all at once, so a backfill floods every network in a minute.

- It runs inside the editor's save request, so a slow network makes Publish hang.

- A publish call that times out has often landed anyway. A blind retry posts the same text twice, and nothing deletes the duplicate.

- Each network counts length differently, so a template that fits one is rejected by another.

- API error messages carry tokens and request bodies. Logged as they come, they leak credentials.

## What it does

- Creates one frozen job per post per network on the first transition into publish. Later saves create nothing.

- Sends outside the editor request, with a daily cap, minimum spacing and backoff.

- Counts length by each network's own rule and shortens the excerpt first, then drops whole hashtags, then cuts the title. The URL is never cut.

- Attaches one image where the network allows it, and requires alt text by default.

- Keeps a log and a job list, with a preview of the text before anything is live.

- Provides wp crosspost commands and a block editor panel.

## How it works

A status transition into publish calls Crosspost::onTransition. It composes the text and image per network and inserts a row into the jobs table. The table has a unique key on post and network, so the database itself enforces one job per pair. One scheduled event a minute ahead is the only side effect. No network call happens in the editor request.

Runner::run takes a lock, turns stuck sending jobs into uncertain, reconciles uncertain jobs, then sends at most one due job per network. The job is marked sending and logged before the first remote call. The adapter returns one outcome: posted, retryable, uncertain, permanent or auth.

An uncertain job is checked without posting again. Mastodon resends with the same Idempotency-Key inside the server's window, then matches recent statuses. Bluesky reads back the record key chosen at creation and resends only when it is provably absent. Threads matches the account's recent posts by normalised text. X is never checked automatically: the plugin uses the create-post endpoint only, so an X post with an unknown outcome waits as unknown until a person resends it.

Storage is three tables (jobs, log, accounts) and non-autoloaded options for credentials.

wp crosspost status
wp crosspost preview 123
wp crosspost queue --state=held
wp crosspost log --since="1 hour ago"

## Guard rails

- A kill switch stops every outbound call. Each network is off until its credentials are verified and a preview of the three latest posts is confirmed.

- The first announcement on a new network waits in a first post review. It applies again after 90 days without a post. Only an administrator's "post now" or an explicit release skips it.

- The daily cap is 10 posts per rolling day by default, with a hard ceiling of 50 per network.

- Posts older than 24 hours at publication are skipped as too old. Queued jobs older than 24 hours go stale.

- The plugin never edits, deletes, hides or replies to a remote post.

- Bluesky accepts app passwords only, and the service URL must be HTTPS.

- Image URLs for Threads are checked as public HTTPS before use. Tokens are scrubbed from logs, notices, REST and CLI output.

## What review changed

- The first post review could be bypassed. A "post now" by any author with publish_posts, or a job rebuilt from cron or CLI with no user, skipped it.

- Reconciliation ignored a 429 cooldown and the needs-attention state, and kept making listing calls and resends to a network it was told to leave alone.

- The kill switch during a Threads text container wait counted as a retryable failure. The attempt counter rose and a retry was scheduled.

- The public address check let through IPv4-mapped IPv6, NAT64, 6to4 and IPv4-compatible forms of private addresses, plus special-purpose ranges. A Bluesky service URL set by constant could also be plain HTTP, which would send the app password in clear text.

Review also moved every table and column name through %i placeholders and raised static analysis from level 6 to level 8.

## Limits and what is next

- One account per network. The tables carry the account id so several can come later.

- One image per post. No threads of posts, polls, video or stories.

- X posts are text only, and an uncertain X post needs a person.

- Threads takes no language tag. Threads images need a public HTTPS URL, otherwise the post goes out as text.

- Bluesky uses app passwords, not the protocol's OAuth flow.

- X's length rules are written from the published rules, with fixture tests. X may change them.

There are no open issues. This is v0.1.0. The suite has 132 tests and 6714 assertions, including six integration tests against a throwaway MySQL 8.0, with the rest on stubs and mocks. Static analysis and code style checks pass. Nothing has been tested against the live networks, and the CI workflow has not run on GitHub yet.

## Install

Requires PHP 8.1 or later and WordPress 6.4 or later, with outbound HTTPS to the networks. WP-Cron or a system cron running wp crosspost run is needed.

composer require indianopinion/crosspost

The package is not on Packagist yet, so add a Composer vcs repository entry for https://github.com/IndianOpinion/crosspost first.

Without Composer, unzip a release into wp-content/plugins/crosspost and activate.

[All 47 utilities](https://indianopinion.org/blog/open-source/) · [crosspost on GitHub](https://github.com/IndianOpinion/crosspost)

Canonical: https://indianopinion.org/blog/open-source/crosspost/

AI disclosure: Every summary and comment here is written by AI and published automatically, without a person reviewing each article. We do no original reporting. How this works: https://indianopinion.org/ai-use-policy/
