UniPost
Dashboard

Receive and reply to X direct messages

Use UniPost Inbox for legacy X direct-message events, private threads, bounded history sync, and idempotent replies.

Basic plan or higherLegacy DM APIPrivate content

1. Confirm DM access

Read account capabilities and require x_inbox.dms_enabled. The connected X account needs dm.read, dm.write, tweet.read, tweet.write, users.read, and offline.access. If any are missing, use the reconnect procedure.

With unipost_managed_app, UniPost manages delivery and counts managed reads, inbound events, and sent DMs against the workspace allowance. With workspace_x_app, your app needs Client ID, Client Secret, app Bearer Token, and Consumer Secret; activity uses your X access and bypasses UniPost X Credits.

2. List private threads

Use the Inbox list reference with source=x_dm. Treat body, author identifiers, and conversation metadata as private customer data; do not copy them into usage keys, logs, or analytics.

3. Send an idempotent DM

The Inbox reply endpoint resolves the persisted conversation or participant and records the outbound item in the same thread. A stable Idempotency-Key prevents an uncertain network response from creating a duplicate message.

4. Backfill recent DM events

The Inbox sync endpoint can request up to 30 days of X DM events. A high managed-X estimate returns a confirmation token before any paid read. Repeat the exact request with that token; changing the account set or request invalidates confirmation.

5. Branch on stable conditions

  • plan_feature_not_available: Inbox requires the Basic plan or higher.
  • x_monthly_usage_limit_exceeded: stop managed-X work until allowance becomes available.
  • x_inbound_daily_cap_exceeded: new inbound DMs are suppressed at the UTC-day safety boundary.
  • x_reconnect_required: reconnect and grant the missing DM permissions.
  • x_write_outcome_pending: reuse the original idempotency key; never blindly resend.

Start from the Inbox API overview. For public conversations, use the X comments guide. Diagnose missing access with the reconnect guide. Inspect live allowance fields in the X Credits API reference and plan the operation mix with the X Credits guide.