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.

---

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 offers two DM endpoints that cover both sending and reading direct messages:

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.

---

How authentication works for DMs

DM endpoints require an auth_token — this is a Twitter session token tied to the account that will send/receive DMs. There are two ways to get one:

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

Understanding Twitter direct message limits is critical for any bulk DM operation or DM bot. There are two layers:

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 can fail for several reasons. Here's what to watch for:

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

Here's what DM operations actually cost on each platform for common workloads:

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

Here's the complete flow for building a Twitter DM bot or outreach system:

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.

---

Quick reference

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.001
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)

A complete Twitter DM bot in Python: log in, fetch DM-eligible followers, send messages with rate-limit-aware delays.

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.

---

Start Sending Twitter DMs

GetXAPI gives you $0.10 in free credits at signup — that's 50 DM sends with no credit card required. Enough to test the full Twitter DM bot workflow above.

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

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