Twitter DM API, Bots, Rate Limits & Errors (2026)

Sending and reading Twitter DMs programmatically is one of the most requested features by developers building Twitter DM bots, outreach tools, customer support systems, and notification services. But the official X API makes it painfully complex, OAuth 2.0 PKCE flows, developer account approvals, and $0.010+ per DM.

This guide covers everything you need to know about the Twitter DM API in 2026, building a DM bot, handling daily rate limits, debugging "sending direct message failed" errors, and the pitfalls that wreck most DM outreach pipelines.

What the Twitter DM API Can Do in 2026

The Twitter DM API gives you programmatic control over sending and reading direct messages on X. With it you can automate outreach to filtered follower lists, send customer notifications, build community management systems that welcome new followers, and run lead qualification pipelines at $0.002 per message.

Outreach automation. Send personalized DMs to a filtered list of followers or prospects. The most common B2B use case: export followers of a competitor or conference account (see the follower export guide), filter by ICP criteria (canDm: true, followers > 500, bio keywords), then send a short, relevant message via the DM API.

Customer notification. Products with a Twitter presence use DMs to send order confirmations, delivery updates, or support ticket replies directly to the user's DM inbox. This is particularly effective for consumer brands where Twitter is a primary customer service channel.

Community management. Automatically send welcome DMs to new followers, thank users who share your content, or route inbound DM keywords to the right support queue. These workflows require both send and read access, GetXAPI's dm/list endpoint covers both.

Lead qualification pipeline. Send a short qualifying message to warm prospects, check replies via dm/list, and route responses to a CRM or Slack notification. A 50-message batch at $0.002 per send costs $0.10 -- the same as the free credit you get at GetXAPI signup.

According to McKinsey's 2025 personalization report, personalized outreach converts at 3-5x the rate of generic mass messaging. The DM API's ability to pull follower profile data (bio, location, follower count) and use it in personalized messages is the key differentiator over email-list-style bulk sends.

---

The problem with the official X API for DMs

As of February 2026, X replaced all fixed pricing tiers with a pay-per-use model. DM access now costs $0.010,$0.015 per API call, and requires a full OAuth 2.0 PKCE flow with dm.read and dm.write scopes.

Here's what that means in practice:

Requirement	Official X API	GetXAPI
Developer account	Required (approval needed)	Not required
OAuth flow	OAuth 2.0 PKCE (3-legged, web server needed)	Bearer token
Cost per DM sent	~$0.015	$0.002
Cost per DM read	~$0.010	$0.002
Rate limit (send)	15 per 15 minutes	No platform cap (~1,000/day Twitter limit)
Rate limit (read)	15 per 15 minutes	900 per 15 minutes
Setup time	Hours (OAuth app, callback URLs, token refresh)	Minutes (API key + auth_token)

The official API also has a known bug where the /2/dm_events endpoint sometimes misses messages that are visible in the Twitter app. This has been reported on the X Developer Community forums and remains unresolved.

---

GetXAPI DM endpoints

GetXAPI provides two DM endpoints at $0.002 per call: POST /twitter/dm/send to send a direct message to any user by username or ID, and POST /twitter/dm/list to read your full DM inbox with cursor-based pagination. Both require an auth_token from the sender's Twitter session, not an OAuth developer app.

Send a DM

POST /twitter/dm/send, $0.002 per call

Parameter	Type	Required	Description
auth_token	string	Yes	Your Twitter session token
recipient_id	string	Either this or username	Recipient's Twitter user ID
recipient_username	string	Either this or ID	Recipient's @handle (without @)
text	string	Yes	Message content

You can use either recipient_id or recipient_username, GetXAPI resolves the username to an ID automatically.

What you get back:

Response field	Description
id	Unique message ID
createdAt	Timestamp (ISO 8601)
senderId	Your Twitter user ID
recipientId	Recipient's Twitter user ID
text	The message you sent
recipient_username	Recipient's @handle

List DMs (Read inbox)

POST /twitter/dm/list, $0.002 per call (~50 messages per page)

Parameter	Type	Required	Description
auth_token	string	Yes	Your Twitter session token
cursor	string	No	Pagination cursor from previous response
count	number	No	Messages per page (default: 50)

What you get back:

Response field	Description
userId	Your Twitter user ID
message_count	Number of messages in this page
has_more	Whether more pages exist
next_cursor	Cursor for next page (pass as cursor)
messages	Array of message objects

Each message in the array contains: id, createdAt, senderId, recipientId, text, and recipient_username.

This is a GetXAPI exclusive, most third-party Twitter APIs only offer DM sending. GetXAPI lets you read your full DM inbox too. For the full list of endpoints across both read and write operations, see the GetXAPI best practices guide.

---

How authentication works for DMs

DM endpoints require an auth_token, a Twitter session token tied to the specific account that will send or receive messages. This token is different from a standard API key. You get it either by extracting the auth_token cookie from a logged-in browser session, or by calling POST /twitter/user_login with your Twitter credentials. Two methods are covered below.

Option 1: Browser cookies

1. Open Twitter/X in your browser and log in
2. Open DevTools (F12) → Application → Cookies
3. Find the auth_token cookie and copy its value
4. Use this value in your API calls

Option 2: Login endpoint

Call POST /twitter/user_login with your Twitter credentials:

Parameter	Type	Required	Description
username	string	Yes	Twitter username
password	string	Yes	Account password
email	string	Recommended	Email for verification (Twitter may require it)
totp_secret	string	If 2FA enabled	TOTP secret key for 2FA

The response includes auth_token, ct0, and twid. You only need the auth_token for DM calls.

Important: Always provide your email in the login request. Twitter's login flow sometimes triggers an email verification step, without it, login fails silently.

---

Before you send: Check if the user accepts DMs

Not every Twitter user has DMs open. If you try to DM someone who has DMs disabled, the request will fail. Save yourself the wasted API call by checking first.

GetXAPI's user endpoints include a canDm field that tells you whether a user accepts DMs:

Endpoint	Returns canDm?	Notes
GET /twitter/user/info	Yes	Quick profile lookup
GET /twitter/user/followers_v2	Yes	Check DM-ability while fetching followers
GET /twitter/user/following_v2	Yes	Check DM-ability while fetching following

Pro tip: If you're building a DM outreach tool, use /twitter/user/followers_v2 to fetch your followers, it returns both the follower list and canDm status in a single call ($0.001). Then only DM the ones where canDm: true.

---

Twitter Direct Message Rate Limits and Daily Caps

Twitter enforces two separate limit layers on DM sending. The API level limits the dm/send endpoint to 1,000 sends per day per Twitter account, and the dm/list read endpoint to 900 calls per 15 minutes. At the account level, Twitter's own spam controls cap daily DMs at roughly 500 for new accounts and up to 1,500 for Premium+ subscribers, regardless of which API you use.

API-level limits (GetXAPI)

Endpoint	Rate limit
dm/send	1,000 per day (per Twitter account)
dm/list	900 per 15 minutes

Twitter account-level limits

Twitter enforces its own daily DM limits that vary by account age and status:

Account type	Approximate daily DM limit
New/unverified account	~500 DMs
Established account	~1,000 DMs
Twitter Blue / Premium+	~1,500 DMs

These limits are enforced by Twitter regardless of which API you use. If you hit the limit, Twitter returns an error and you need to wait until the next day.

---

Error handling for DMs

DM operations fail for predictable reasons that you can handle programmatically. The five most common failures are an expired auth_token, an invalid recipient, a recipient with DMs disabled (canDm: false), a hit daily cap returning 429, and an invalid GetXAPI key returning 401. Each maps to a specific fix rather than a generic retry.

Error	Cause	What to do
Invalid auth_token	Token expired or malformed	Re-authenticate via login endpoint or browser cookies
User not found	Invalid recipient_id or recipient_username	Verify the user exists with /twitter/user/info
Cannot send DM	Recipient has DMs disabled	Check canDm field before sending
Rate limited	Hit daily DM cap	Wait 24 hours or use a different account
401 Unauthorized	Invalid API key	Check your GetXAPI API key

Retry strategy: Only retry on 429 (rate limit) and 5xx (server error) responses. Don't retry 400-level errors, they indicate a problem with your request that won't be fixed by retrying.

---

Cost comparison: DMs at scale

At $0.002 per send, GetXAPI is 7.5x cheaper than the official X API's $0.015 per DM and the only third-party provider that also covers inbox reading at the same per-call rate. The table below shows total cost for common workload sizes across the three providers that support DM sending.

Operation	Official X API	twitterapi.io	GetXAPI
Send 100 DMs	$1.50	$0.30	$0.20
Send 1,000 DMs	$15.00	$3.00	$2.00
Read 10,000 messages	$100.00	N/A	$0.40
Send 1,000 DMs + read inbox	$25.00	$3.00+	$2.40

GetXAPI is 7.5x cheaper than the official X API for DM sending, and is the only third-party API that offers DM inbox reading.

---

Building a Twitter DM Bot, Step-by-Step Workflow

A Twitter DM bot built on GetXAPI follows five steps: authenticate to get an auth_token, fetch followers with the followers_v2 endpoint and filter by canDm: true, loop through recipients calling dm/send with a 2-5 second delay, monitor the inbox via dm/list for replies, and log every send attempt to handle errors and skip already-contacted accounts.

Step 1: Get your auth_token

Call POST /twitter/user_login with your Twitter credentials. Store the returned auth_token securely, you'll use it for all DM operations.

Step 2: Build your recipient list

Fetch your followers using GET /twitter/user/followers_v2. This returns both follower profiles and the canDm field. Filter for users where canDm: true.

Step 3: Send DMs

For each recipient, call POST /twitter/dm/send with their username or user ID. Add a delay between sends (e.g., 2-5 seconds) to avoid triggering Twitter's anti-spam detection.

Step 4: Monitor your inbox

Use POST /twitter/dm/list to check for replies. Paginate with cursor until has_more: false to get all messages.

Step 5: Handle errors gracefully

If a DM fails, check the error type. Don't retry client errors (400). For rate limits (429), wait and retry with exponential backoff. Store failed recipients to retry later.

Test your setup with curl

Before writing a full bot, verify your auth_token works with a quick curl:

# Step 1: Get auth_token
curl -X POST https://api.getxapi.com/twitter/user_login \
  -H "Authorization: Bearer $GETXAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"username": "your_handle", "password": "your_pass", "email": "you@example.com"}'

# Step 2: Send a DM using the returned auth_token
curl -X POST https://api.getxapi.com/twitter/dm/send \
  -H "Authorization: Bearer $GETXAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auth_token": "YOUR_AUTH_TOKEN", "recipient_username": "testhandle", "text": "Hello from GetXAPI"}'

A successful send returns a JSON object with an id field (the message ID). A 400 response with "Cannot send DM" means the recipient has DMs disabled -- pre-check canDm to avoid this.

---

Quick reference

The five DM-related endpoints and their costs: send a DM via POST to /twitter/dm/send at $0.002, read the inbox via POST to /twitter/dm/list at $0.002, get an auth token via /twitter/user_login at $0.01, check a single user's DM status via GET /twitter/user/info at $0.001, and bulk-check followers with canDm included via GET /twitter/user/followers_v2 at $0.001.

What	Endpoint	Method	Cost
Send a DM	/twitter/dm/send	POST	$0.002
Read DM inbox	/twitter/dm/list	POST	$0.002
Get auth token	/twitter/user_login	POST	$0.01
Check canDm	/twitter/user/info	GET	$0.001
Check canDm (bulk)	/twitter/user/followers_v2	GET	$0.001

---

Send a Twitter DM in Python (Full Code)

This is a complete Twitter DM bot in Python: it logs in via the GetXAPI login endpoint to get an auth_token, fetches your followers and filters to those where canDm is true, then sends each a message with a 3-second delay to avoid Twitter's anti-spam detection. All in 30 lines, no OAuth setup required.

import os
import time
import requests

API_KEY = os.environ["GETXAPI_KEY"]
HEADERS = {"Authorization": f"Bearer {API_KEY}"}

# Step 1: Get auth_token from login (or use browser cookie)
login = requests.post(
    "https://api.getxapi.com/twitter/user_login",
    json={
        "username": os.environ["TWITTER_USERNAME"],
        "password": os.environ["TWITTER_PASSWORD"],
        "email": os.environ["TWITTER_EMAIL"],
    },
    headers=HEADERS,
).json()
auth_token = login["auth_token"]

# Step 2: Fetch followers + canDm flag
followers_resp = requests.get(
    "https://api.getxapi.com/twitter/user/followers_v2",
    params={"userName": os.environ["TWITTER_USERNAME"]},
    headers=HEADERS,
).json()
dm_eligible = [f for f in followers_resp["followers"] if f.get("canDm")]

# Step 3: Send DMs with rate-limit-aware delay
for follower in dm_eligible[:50]:  # respect daily cap
    resp = requests.post(
        "https://api.getxapi.com/twitter/dm/send",
        json={
            "auth_token": auth_token,
            "recipient_username": follower["userName"],
            "text": f"Hi @{follower['userName']}, thanks for following!",
        },
        headers=HEADERS,
    )
    if resp.status_code == 200:
        print(f"✓ Sent to @{follower['userName']}")
    else:
        print(f"✗ Failed for @{follower['userName']}: {resp.json()}")
    time.sleep(3)  # 3-sec delay to avoid Twitter anti-spam

This is a working Twitter DM bot in 30 lines. For more Python patterns (async DMs, retry logic, queue-based outreach), see the Python Twitter API tutorial.

---

Node.js: Send DMs Async

The TypeScript implementation below mirrors the Python workflow but uses async/await and typed interfaces, making it suitable for production Node.js services. The sendDmBatch function loops with a configurable inter-message delay, catches per-recipient errors without aborting the entire batch, and returns a message ID for each successful send.

import fetch from "node-fetch";

const API_KEY = process.env.GETXAPI_KEY!;
const HEADERS = { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" };

interface LoginResponse { auth_token: string; }
interface DmSendResponse { id: string; createdAt: string; }

async function getAuthToken(username: string, password: string, email: string): Promise<string> {
  const res = await fetch("https://api.getxapi.com/twitter/user_login", {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({ username, password, email }),
  });
  if (!res.ok) throw new Error(`Login failed: ${res.status}`);
  const data = (await res.json()) as LoginResponse;
  return data.auth_token;
}

async function sendDm(authToken: string, recipientUsername: string, text: string): Promise<DmSendResponse> {
  const res = await fetch("https://api.getxapi.com/twitter/dm/send", {
    method: "POST",
    headers: HEADERS,
    body: JSON.stringify({ auth_token: authToken, recipient_username: recipientUsername, text }),
  });
  if (!res.ok) {
    const err = await res.json() as { message?: string };
    throw new Error(`DM failed for @${recipientUsername}: ${err.message ?? res.status}`);
  }
  return res.json() as Promise<DmSendResponse>;
}

async function sendDmBatch(
  authToken: string,
  recipients: string[],
  getMessage: (handle: string) => string,
  delayMs = 3000
): Promise<void> {
  for (const handle of recipients) {
    try {
      const result = await sendDm(authToken, handle, getMessage(handle));
      console.log(`Sent to @${handle}: message ID ${result.id}`);
    } catch (err) {
      console.error(`Skipped @${handle}:`, (err as Error).message);
    }
    await new Promise(r => setTimeout(r, delayMs));
  }
}

// Usage
const authToken = await getAuthToken(
  process.env.TWITTER_USERNAME!,
  process.env.TWITTER_PASSWORD!,
  process.env.TWITTER_EMAIL!
);

const recipients = ["alice", "bob", "charlie"];
await sendDmBatch(authToken, recipients, (handle) => `Hi @${handle}, thanks for connecting!`);

The sendDmBatch function loops with a configurable delay and catches per-message errors without aborting the batch. Permanent failures (disabled DMs, blocked accounts) are logged and skipped. Rate-limit errors would surface as exceptions on the fetch call; add a check for res.status === 429 and increase delay accordingly.

DM Templates and Personalization

Generic DM copy gets ignored. Personalization at the canDm: true filter level means you already know the recipient is reachable. Go further by using profile data from the followers endpoint to customize the message.

A template pattern using follower data:

def build_dm_text(follower: dict, context: str = "your startup") -> str:
    """Build a personalized DM using available follower profile fields."""
    name = follower.get("name", "there")
    location = follower.get("location", "")
    bio = follower.get("description", "")

    # Personalization tier 1: use first name if parseable
    first_name = name.split()[0] if name else "there"

    # Personalization tier 2: reference location if present
    location_line = f"I saw you're in {location}. " if location else ""

    return (
        f"Hey {first_name}, {location_line}"
        f"Building something in {context} space and thought you might find this useful. "
        f"Would love to share a quick resource. Mind if I send it over?"
    )

# Example output for a follower with location data:
# "Hey Sarah, I saw you're in Austin. Building something in B2B SaaS space..."

Keep DMs under 280 characters where possible. Longer messages technically send but display truncated in the mobile app notification banner, which reduces open rates.

Production DM Pipeline: Monitoring and Audit

A production DM pipeline needs a per-send audit log so you can skip already-contacted recipients, detect error patterns (a 40% failure rate on "Cannot send DM" signals you are targeting non-followers), and reconstruct the send history if your process crashes mid-batch. A simple SQLite table with one row per send attempt covers all three needs without external infrastructure.

import sqlite3
from datetime import datetime

def init_db(db_path: str = "dm_log.db") -> sqlite3.Connection:
    conn = sqlite3.connect(db_path)
    conn.execute("""
        CREATE TABLE IF NOT EXISTS dm_log (
            id TEXT PRIMARY KEY,
            recipient TEXT,
            text TEXT,
            status TEXT,
            error TEXT,
            sent_at TEXT
        )
    """)
    conn.commit()
    return conn

def log_dm(conn: sqlite3.Connection, dm_id: str | None, recipient: str,
           text: str, status: str, error: str = "") -> None:
    conn.execute(
        "INSERT OR REPLACE INTO dm_log VALUES (?, ?, ?, ?, ?, ?)",
        [dm_id or f"err_{recipient}", recipient, text, status, error,
         datetime.utcnow().isoformat()]
    )
    conn.commit()

The audit log gives you a per-recipient send history, lets you skip recipients you've already contacted, and surfaces error patterns (if 40% of sends are failing with "Cannot send DM", you're targeting too many non-followers).

Compliance Considerations for DM Campaigns

The Twitter Developer Agreement restricts automated DM sending to non-spam, non-harassment use cases. In practice this means only messaging users who have shown prior interest, varying message copy across sends, honoring unsubscribe requests that arrive as replies, and never messaging accounts where canDm is false or who have blocked you. Key compliance guidelines:

• Only DM users who have shown prior interest (followers, engagers)
• Include an opt-out mechanism or honor unsubscribe requests in replies
• Do not send the same message verbatim to more than a small batch per day
• Do not DM users who have blocked you or whose canDm is false

GetXAPI's DM endpoint enforces the canDm check by returning an error if the recipient has DMs disabled. Build your own filter before sending to avoid wasting credits and triggering spam flags on the sending account.

For a comparison of DM costs across providers, see the best Twitter API for scraping guide which covers DM pricing in the cost table. For following and followers management that feeds your DM list, see the follower export guide.

Start Sending Twitter DMs

GetXAPI gives you $0.10 in free credits at signup, which covers 50 DM sends at $0.002 each, with no credit card required. That is enough to run the full bot workflow above end-to-end: login, follower fetch, send, and inbox read.

1. Sign up at getxapi.com, instant API key, no developer account needed
2. Get your auth_token via the login endpoint or browser cookies
3. Send your first DM with POST /twitter/dm/send
4. Check full pricing for DM endpoints at $0.002 per call

For building the follower list that feeds your DM outreach, see the follower export guide. For migrating an existing twitterapi.io DM setup to GetXAPI at 3x lower cost, see the twitterapi.io migration guide.

Inbox Reading: Reading DM Replies at Scale

Most DM bot guides stop at sending. The more valuable capability is reading replies. GetXAPI's dm/list endpoint lets you pull your full DM inbox, identify replies to your outreach messages, and route them to a CRM or notification system.

A practical inbox reader:

def read_dm_inbox(auth_token: str, api_key: str, max_pages: int = 10) -> list[dict]:
    """Pull DM inbox, return all messages up to max_pages pages."""
    base_url = "https://api.getxapi.com/twitter/dm/list"
    headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
    all_messages = []
    cursor = None
    for _ in range(max_pages):
        payload = {"auth_token": auth_token}
        if cursor:
            payload["cursor"] = cursor
        resp = requests.post(base_url, headers=headers, json=payload, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        all_messages.extend(data.get("messages", []))
        if not data.get("has_more"):
            break
        cursor = data.get("next_cursor")
    return all_messages

def find_replies_to_outreach(messages: list[dict], outreach_ids: set[str]) -> list[dict]:
    """Filter inbox messages that are replies to known outreach sends."""
    return [m for m in messages if m.get("in_reply_to_id") in outreach_ids]

The find_replies_to_outreach function requires tracking the message IDs returned by dm/send (the id field in the send response). Match those against the in_reply_to_id field on inbox messages to identify which outreach messages got replies.

Sales teams that follow up on inbound engagement within one hour consistently close at far higher rates than teams that wait a full day, a pattern documented across multiple inbound-sales studies. The inbox reader enables same-hour reply detection and routing.

Why DM Deliverability Matters More Than Delivery Rate

Delivery rate (did the message send without error?) and deliverability (did the message reach the main inbox instead of message requests?) are different metrics. A 100% delivery rate does not guarantee 100% deliverability.

Twitter routes DMs to "Message Requests" when the sender and recipient do not follow each other. Recipients see a different notification for message requests and open them at lower rates. Improving deliverability requires one of these conditions: the recipient follows you back, you follow each other mutually, or the recipient has previously accepted a message request from your account.

Practical deliverability improvement tactics:

First, only DM your own followers. Recipients who follow you already have a relationship signal with your account, which Twitter treats favorably for inbox placement. Filter your outreach list to followers using the follower export endpoint, then check canDm: true.

Second, engage before you DM. A reply or like on a prospect's tweet before sending a DM increases the mutual recognition signal that Twitter's routing algorithm uses for inbox placement decisions.

Third, avoid exact-duplicate messages. Twitter's anti-spam system flags accounts that send identical text to many recipients in quick succession. Even minor personalization (using the recipient's name, referencing their bio keyword) reduces the spam-detection risk.

For acquiring the follower list to target, see the follower export guide. For the full API setup guide if you are starting from scratch without an API key, see the Twitter API key guide.

Scaling DM Campaigns Across Multiple Twitter Accounts

A single Twitter account is limited to approximately 1,000 DMs per day for established accounts. For teams that need to send more than 1,000 DMs per day, the strategy is account pooling: maintain multiple Twitter accounts and distribute DM sends across the pool.

Each account in the pool requires its own auth_token. GetXAPI's login endpoint makes it straightforward to maintain a pool:

The pool management pattern: store credentials for each account securely, rotate auth tokens on a schedule (tokens expire after approximately 6 hours of inactivity), and distribute sends across accounts based on remaining daily quota. Track per-account send counts in a local store and rotate to the next account when the current one reaches 800 sends (80% of the ~1,000 limit, leaving buffer for manual sends).

Account pool hygiene is critical. Accounts that trigger spam flags get their DM capabilities restricted first (soft limit: sends fail silently), then suspended. Signs that an account is being restricted: sends return success status but the recipient never receives the message, or the delivery rate (confirmed reads via inbox check) drops below 50%. When this happens, pause that account and warm a replacement.

Account warming is the process of establishing a credible activity history on a new account before using it for DM campaigns. A new account sending 1,000 DMs on its first day will be flagged immediately. A two-week warming period (10-20 organic tweets, follows, engagement with content) establishes enough behavioral signal to avoid immediate restriction.

For most teams at scale, 3-5 accounts in rotation provides sufficient daily send capacity (3,000-5,000 DMs/day) with redundancy against individual account restrictions. At $0.002 per DM, 5,000 DMs per day costs $10/day or $300/month in API costs -- negligible compared to the outreach infrastructure cost of running the accounts themselves.

The DM API cost structure also means the limiting factor in scaling DM campaigns is account quality and daily limits enforced by Twitter, not API cost. Once you have cleared the API cost as a constraint, the investment shifts to building quality account portfolios, which is an operational rather than a technical challenge. Most B2B teams operating at 1,000-5,000 DMs per day find the ROI positive within the first month if their ICP targeting is accurate.

Read the full API documentation for detailed request/response schemas and more examples.