POST https://xquik.com/api/v1/x/dm/{userId}
10 credits per send · Compare plansA write that must sign in to your X account first adds 10 credits. Xquik refunds them if the sign-in fails. A sign-in that works keeps them, even if X then refuses the write. See the X sign-in fee.
Send direct messages with the Twitter DM API
Use this route for approved, one-to-one messages. It sends text or one uploaded media attachment. SDKs, support tools, and server jobs can call it. Choose the connected X account and the recipient’s numeric user ID. Use Twitter profile lookup when you only know a username. Follow X’s Direct Message rules for every message.Authenticate and select the recipient
Authenticate with anx-api-key header or an OAuth bearer token.
The connected X account sends the message on the user’s behalf.
The path userId identifies the recipient, not the sender.
Send only messages approved by your workflow.
Honor recipient privacy, consent, and opt-out decisions.
Read DM history only for approved conversation context.Send text or one media attachment
Provide non-emptytext for every direct message.
Upload media first with Upload Media.
Place its mediaId inside a one-item media_ids array.
The upload costs another 10 credits.
Empty or multi-item arrays return 400 invalid_input.
This route also rejects reply_to_message_id.
It does not send group messages or accept public media URLs.Poll and verify the direct message
A200 response contains a terminal write action.
A 202 response requires polling through statusUrl.
Wait for terminal: true before closing the send job.
Xquik settles a pending DM within 15 minutes of the send.successwithmessageIdmeans X sent it. You pay once.failedwithx_dm_not_sentmeans Xquik found no sign of the DM. You pay nothing, andsafeToRetryistrue. If you deleted the DM on X (Twitter), check before you send it again.expiredmeans Xquik could not confirm the send. You pay nothing. Check the conversation before you send again.
writeActionId, recipient ID, account, request hash, and messageId.
Delete DM takes that messageId later.
If the connection drops, retry with the same idempotency key.
Never create another write while the first action remains nonterminal.
Each account gets 120 X (Twitter) actions per minute.Handle every Twitter DM API response
Fix request fields after400.
Replace authentication after 401, then add credits after 402.
Reconnect the X account after 403.
Keep the original request after a 409 idempotency conflict.
422 x_dm_not_allowed means this sender cannot message that person.
Try another approved sender or ask the person to allow DMs.
Honor Retry-After after 429.
429 x_rate_limited means X paused DMs from that account.
Its DMs then get 429 until X’s reset, and Xquik sends nothing to X.
You pay nothing. Retry-After and nextAction.afterMs give the wait.
After 500 or 503, inspect safeToRetry before retrying.Twitter DM API questions
Can I automate customer support direct messages?
Yes. Queue approved replies and store the exact sent text. Avoid unsolicited bulk messaging and honor every opt-out.Can I send images or video through the API?
Upload the file first, then send its singlemediaId.
This endpoint accepts one attachment per message.Does this endpoint retrieve message history or create webhooks?
No. Use Get DM History for prior messages. This send route does not configure incoming-DM notifications.Can third-party tools and generated SDKs call this route?
Yes. Use the documented REST fields and authentication. Leavereply_to_message_id unset when a generated SDK exposes it.Headers
Path parameters
Body
Response
Durable write recovery
- Store
id, the nestedhashinrequest,billing, andstatusUrl. - Poll after
Retry-AfterorpollAfterMswhenterminalisfalse. - Retry only when
safeToRetryistrue. - Use a new key when
nextAction.requiresNewIdempotencyKeyistrue.
200 terminal or 202 active
- After HTTP
200, store the result and settled billing. - After HTTP
202, poll the same action. Never submit another write. - After HTTP
400, fix the named field. Use a new idempotency key. - After HTTP
401, fix authentication. Do not retry unchanged. - After HTTP
402, fund the account before another write. - After HTTP
403, reconnect the account. - After HTTP
409, keep the original action. Use a new key for new input. - After HTTP
422, fix the rejected request before retrying. - After HTTP
429, wait forRetry-After. FollownextAction.
Response examples
200 example
202 example
- 400
{ "error": "missing_idempotency_key", "message": "Idempotency-Key is required. Generate one unique key for this write.", "charged": false, "chargedCredits": "0", "retryable": false, "safeToRetry": true } - 401
{ "error": "unauthenticated", "message": "Authentication required. Provide a valid API key or bearer token." } - 402
{ "error": "insufficient_credits", "message": "Insufficient credits. Top up or subscribe to continue." } - 403
{ "error": "api_key_paused", "message": "This API key is paused. Resume it at dashboard.xquik.com/api-keys to use it again." } - 404
{ "error": "account_not_found", "message": "X account not found. Connect it first at /dashboard/x-accounts." } - 409
{ "error": "idempotency_conflict", "message": "Idempotency-Key was already used with a different request.", "charged": false, "chargedCredits": "0", "retryable": false, "safeToRetry": true } - 422
{ "error": "x_rejected", "message": "X rejected this request. Check what you sent & the account on x.com before you try again." } - 429
{ "error": "rate_limit_exceeded", "message": "Too many requests. Try again later.", "retryAfter": 60 } - 500
{ "error": "x_write_failed", "message": "Write action failed unexpectedly. Contact support if this persists." } - 503
{ "error": "write_tracking_unavailable", "message": "Write tracking unavailable. Try again.", "charged": false, "chargedCredits": "0", "retryable": true, "safeToRetry": true }