Skip to content

X customer publishing

Implemented

Connect your X account, approve an exact post, and read saved publication evidence from the worker.

Connect a customer-owned X account to a workspace. Prepare posts through the post tools. The owner selects the account and approves the exact post in the browser. A queued job is not a provider receipt. Live customer publication has not been verified.

Connect#

Call start_x_connection and give connectionUrl to the owner. The link is /connect/x. The owner signs in if needed, and goes straight to X. On the Connections page and in setup, Connect is the same link. The owner grants account identity reads, post reads and writes, media uploads, and refresh access at X. X returns the owner to Connections or to setup, with a connected or error notice. Manage shows reconnect and disconnect. Read get_x_status after the callback. This read returns saved state and does not contact X.

One active X account is supported per workspace. X and Instagram use separate credentials and worker records. Reconnect replaces the X connection generation. Disconnect blocks new provider work and attempts provider revocation. A request already sent cannot be recalled.

get_x_status lists saved connections. An empty connections list means no X account is connected: start start_x_connection and give the owner its connectionUrl. Status reconnect-required on a saved connection means reconnect. X_NOT_CONNECTED and X_RECONNECT_REQUIRED come from Dashboard post performance, not from this read. See X publishing errors.

Prepare and approve#

  1. Create a post and edit a draft with the existing post tools.
  2. Call prepare_x_publication with the postId.
  3. Give reviewUrl to the owner. The URL grants no permission.
  4. The owner selects Use account on X and checks the text, media, and account in the preview.
  5. The owner selects Publish on X, checks the text, media, and account in the confirmation, then selects Publish now. This approves the saved post exactly as shown.
  6. Read get_x_status with postId. Keep providerPostId, url, and verified separate from queue status.

A repeated approval uses the same request ID and identical input. If a concurrent call queues it during preparation, the server reads and returns that saved operation. It does not queue a second publication.

Approval locks the draft. The worker must finish within ten minutes of approval. New provider calls stop 30 seconds before the permit ends. An owner can withdraw queued work. Changed content, account, or media stops publication. A lost provider response produces an unknown outcome; the worker does not repeat that write.

Updated 2026-10-28. Publish now sends the review digest of the post that the owner opened. If the saved post changed after that, for example after an agent edit, the approval is refused with CONTENT_CHANGED. Nothing is queued. The page reads the post again: the owner checks it, then publishes again.

Updated 2026-10-13. When the worker stops a step before it sends the request to X, for example because the permit has too little time left, the publication is failed, not unknown. Nothing was posted. The saved failure keeps the exact internal error code for support.

Automatic publishing#

The owner can give this agent Publish across all owned workspaces in Agents, with typed confirmation allow agent. Read list_workspaces.access.canPublish. The post must also have publishMode: "automatic". Set it, and channel: "x", with edit_post from the user's instruction. The server fills the connected account. Then call publish_x_post. It runs the same checks and worker as an owner approval, and saves the approval with the agent's permission. Without the mode or the permission, it saves nothing and returns mode: "owner_review" with reason and review.url. Turning off Publish keeps queued and scheduled posts. Disconnecting the agent cancels its unsent work in all workspaces; disconnecting X stops new provider work. ShipContent sets no daily post limit; X rate limits still apply.

Insights#

Updated 2026-11-19: get_post_metrics returns views (impressions), likes, comments (replies), shares (reposts) and quotes for each published post. refresh_post_metrics reads them from X with the saved X connection. The connection already holds the tweet.read permission, so the owner has nothing more to allow. If X asks for a new login, the row fails with reconnect. See Read post performance.

Limits#

  • Text is required, with at most 280 weighted characters. Mentions are excluded.
  • Use text only, one JPEG/PNG image up to 5 MB, or one MP4 video up to 50 MB and 140 seconds.
  • Media uploads use bounded segments and at most 20 processing checks.
  • Link-format, carousel and thread publication are Coming soon. Replies, quotes, polls, recurring schedules, automatic analytics and paid X Ads are not included.
  • A provider acknowledgement records publication. Failed readback leaves verification pending; it never triggers another post.
  • Publication history remains immutable after cancellation or failure. Read an unknown outcome before preparing another post.

Operator setup#

Register a confidential X web app with the exact callback URL https://<mcp-host>/integrations/x/callback. The server builds it from the origin of SHIPCONTENT_MCP_AUDIENCE; production uses https://mcp.shipcontent.com/integrations/x/callback. The browser return on the MCP host redirects to the owner host, where the owner is signed in. Store client credentials and the X vault key ring on the server. Use separate restricted connection and worker database logins. Publication is on when the client credentials are set. X bills API use, including posts with URLs and media uploads, to the developer account; ShipContent sets no API budget. Verify app eligibility and the payment method on the X developer account before a live pilot. See local setup and hosted setup.

Scheduled delivery#

The owner checks the exact saved content and destination, then confirms its time in the post editor. An agent with Publish can save an automatic post schedule through prepare_post_schedule; otherwise the owner confirms the proposal. Updated 2026-11-19: the agent schedule uses the one connected account of the workspace, so the owner does not select it for each post. Before this date, the schedule of a post that an agent made failed until the owner selected the account. publish_post publishes an automatic post now through the same checks. Scheduled work uses the existing provider worker, current account/media checks and durable recovery. A planned date never publishes.

Updated 2026-10-14. Scheduled X posts need a connected account. When billing enforcement is enabled, the current plan must also allow publishing and scheduling, except for an owner on the billing enforcement bypass. See billing. No provider-verification flag controls them. A linked job keeps its existing recovery path. No controlled live delivery or intended-customer approval is recorded for this feature. See scheduling errors.

Scheduled X supports text, one JPEG/PNG image or one MP4 under the same limits above. X_NOT_CONFIGURED needs operator setup. It does not ask for an account reconnect.

Updated 2026-10-16. When billing enforcement is enabled, approval reserves one X publication place. The worker checks the current plan and usage period before it sends the post. A provider acknowledgement uses that place once. A definite unsent failure or cancellation releases it; an unknown publication keeps it for reconciliation. PLAN_LIMIT_REACHED includes the named limit and a Billing recovery link. Existing saved results remain readable after a plan change.