Skip to main content
POST
/
x
/
dm
/
{userId}
Send DM
curl --request POST \
  --url https://xquik.com/api/v1/x/dm/{userId} \
  --header 'Content-Type: <content-type>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "account": "<string>",
  "text": "<string>",
  "media_ids": [
    "<string>"
  ]
}
'

Documentation Index

Fetch the complete documentation index at: https://docs.xquik.com/llms.txt

Use this file to discover all available pages before exploring further.

10 credits per call · All plans from $0.00012/credit
Send a text DM from one connected X account to the recipient userId. For media DMs, upload first with POST /x/media, pass the returned mediaId as the only media_ids item, and store the returned messageId. Use public media URLs with POST /x/tweets; this DM endpoint accepts one uploaded media ID instead. 
curl -X POST https://xquik.com/api/v1/x/dm/44196397 \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "myxaccount",
    "text": "Hello from Xquik!"
  }' | jq
The Node.js, Python, and Go examples convert the response into one DM send row. Store message_id, user_id, account, send_status, optional media_id, media_ids, and source_endpoint. For media DMs, keep media_ids as the one-item request array and set media_id to the uploaded media ID that you passed as that single item.

​
Send with media

Upload media first with Upload Media, then pass the returned mediaId as the only media_ids item. 
curl -X POST https://xquik.com/api/v1/x/dm/44196397 \
  -H "x-api-key: xq_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "account": "myxaccount",
    "text": "Here is the requested image.",
    "media_ids": ["1893726451023847424"]
  }' | jq
media_ids must contain exactly one uploaded media ID. Empty arrays, multiple IDs, and reply_to_message_id return 400 invalid_input.
Generated SDKs can expose reply_to_message_id while the REST route rejects it. Leave it unset. Pass exactly one uploaded media ID in media_ids, then store the returned messageId with that media ID.

​
Media DM result handoff

After the media DM send returns 200 OK, store the returned messageId with the uploaded media ID and recipient user ID so support logs, CRM records, queues, or agent memory can reconcile the attachment with the sent message. 
{
  "record_type": "dm_media_send",
  "message_id": "1893726451029384192",
  "user_id": "44196397",
  "account": "myxaccount",
  "media_ids": ["1893726451023847424"],
  "media_id": "1893726451023847424",
  "send_status": "sent",
  "handoff_format": "jsonl"
}
Keep media_ids as a one-item array in the request, keep media_id as the original POST /x/media result, and use message_id as the external DM identifier after the send succeeds.

​
Direct message handoff

Use POST /x/dm/{userId} when a support, sales, community, CRM, or agent workflow needs to send an auditable direct message from a connected X account. If you only have a username, look up the recipient first with GET /x/users/{id}. If the workflow needs conversation context, read the latest messages with GET /x/dm/{userId}/history before sending.

messageId

Store messageId as the external message ID for support logs, CRM records, queues, or agent memory.

success

Mark the send job complete after a 200 OK response.

userId

Keep the recipient X user ID from the path with the send job.

account

Store the connected X account that sent the DM.

text

Store the exact message text sent. Add your own sent_at timestamp when downstream systems need it.

media_ids[0]

Store the uploaded media ID when the DM includes one attachment from POST /x/media.
This endpoint costs 10 credits per send. Uploading media first with POST /x/media is a separate 10-credit call. Do not retry 422 x_dm_not_allowed unchanged; use another permitted connected account or ask the recipient to allow messages.

​
Headers

​
x-api-key
string
required
Your API key. Session cookie authentication is also supported. Generate a key from the dashboard.
​
Content-Type
string
required
Must be application/json.

​
Path parameters

​
userId
string
required
The X user ID of the recipient.

​
Body

​
account
string
required
X username or account ID of your connected account to act as.
​
text
string
required
Non-empty message text to send. If X rejects oversized content, the API returns 422 x_content_too_long.
​
media_ids
string[]
Optional one-item array containing an uploaded media ID. Upload media first with Upload Media, then pass the returned mediaId as the only array item. Empty arrays and multiple IDs are rejected.

​
Response

​
messageId
string
The ID of the sent message.
​
success
boolean
Always true on success.
{
  "messageId": "1893726451029384192",
  "success": true
}
Related: Direct Message Workflow for lookup, history sync, messageId storage, and media handoff; Get User to look up a user’s ID before messaging; Get DM History to sync participant-scoped messages; Upload Media to create the one mediaId allowed in media_ids.
Last modified on May 23, 2026