x-dms — Unofficial X (Twitter) DM Sync + Send (spec repo)

x-dms is a public specification + coordination repo for building an unofficial connector that can:

1. Sync X/Twitter Direct Messages (DMs) for multiple accounts (history + incremental)
2. Send DMs on behalf of those accounts

This project intentionally does not use the official X API. It targets session-based access (browser cookies / logged-in session state) and requires per-account proxy support.

This repo focuses on what needs to be built. Implementations can be done in any language/runtime and may live in separate repos.

What contributors should build

See:

• docs/WHAT_WE_NEED.md — exact requirements + MVP definition
• docs/INTERFACES.md — suggested language-agnostic interface contract
• docs/RISKS_AND_GUARDRAILS.md — security/legal guardrails

Key requirements (summary)

• Cookie-based account connection (cookies-first)
• DM backfill + incremental sync with checkpoints + de-duplication
• DM sending with retries + idempotency
• Per-account proxy support
• Strong secret handling (never log cookies)

Security & privacy

This project handles sensitive data (cookies, private DMs, proxy credentials). Please read SECURITY.md.

Contributing

See CONTRIBUTING.md.

Disclaimer

Unofficial integration. Contributors and users are responsible for complying with X’s Terms and applicable laws.