Send a Reddit Direct Message via HTTP
Send a direct message to any Reddit user via a single HTTP call. No browser automation, no captcha at send time, just paste cookies and the message body.
/api/reddit/dm$0.025 / callRequest Body
Cookies are passed as flat top-level fields (same shape as /comment and /vote).
| Field | Type | Required | Description |
|---|---|---|---|
to_username | string | one of | Target username (resolved internally to t2_xxx; when our lookup is refused, your own session is asked once before giving up) |
to_user_t2 | string | one of | Target t2_xxx ID directly, skips the username lookup, ~300ms faster |
message | string | yes | Plain-text DM body |
reddit_session | string | yes | Session cookie from /api/reddit/login |
loid | string | yes | Long-lived account identifier cookie |
csrf_token | string | yes | Anti-CSRF cookie |
proxy | object | string | no | Sticky IP for this account, {server, username?, password?} or a URL string. Use the same proxy you passed to /login. Omit to use our pool. See Per-account proxies. |
Example
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{
"to_username": "Ok-Establishment9204",
"message": "hey!",
"reddit_session": "eyJhbGc...",
"loid": "000000...",
"csrf_token": "1c0819..."
}' \
"https://api.redditapis.com/api/reddit/dm"const response = await fetch("https://api.redditapis.com/api/reddit/dm", {
method: "POST",
headers: {
Authorization: "Bearer TOKEN",
"Content-Type": "application/json",
},
body: JSON.stringify({
to_username: "Ok-Establishment9204",
message: "hey!",
reddit_session: "eyJhbGc...",
loid: "000000...",
csrf_token: "1c0819...",
}),
});import requests
response = requests.post(
"https://api.redditapis.com/api/reddit/dm",
json={
"to_username": "Ok-Establishment9204",
"message": "hey!",
"reddit_session": "eyJhbGc...",
"loid": "000000...",
"csrf_token": "1c0819...",
},
headers={"Authorization": "Bearer TOKEN"},
)Success Response
{
"success": true,
"to": "t2_ugmf7dmn",
"room_id": "!hdstiJypyVtzbpoUJZe9mUc-zl-5BnADoRlS7h4itZg:reddit.com",
"event_id": "$u7UA6fbMCcnpk5Pzx-Gv71kDuaEKYbXv0SeamHSDCaQ",
"delivered": true,
"delivery": "confirmed"
}delivered: true means Reddit's chat server holds the message. When the final send step times out after the message went out, we read the conversation back: if the message is there, the answer is still 200 with its event_id and "confirmed_by": "read_back".
Errors
| Status | Meaning |
|---|---|
400 | Missing message, no recipient, bad to_user_t2 shape, or missing required cookies; or proxy is malformed (INVALID_PROXY), or a proxy-shaped field was sent as a top-level string (INVALID_FIELD), see Per-account proxies |
401 | Missing Bearer token |
403 | Invalid Bearer token |
403 | The recipient's Reddit settings do not accept chat requests from the sending account (code: "recipient_not_accepting_chats", kind: "recipient-not-accepting-chats"). Nothing was sent; retrying will not help. |
404 | to_username names a Reddit account that does not exist or is suspended (kind: "recipient-not-found"). Nothing was sent. |
502 | Could not send the DM, for example because the sender account is shadowbanned/spam-flagged |
502 | delivery: "unconfirmed": the send step did not answer after the message went out, and reading the conversation back did not show it (read_back: "not_found") or failed (read_back: "failed"). The message may still have arrived. The response carries room_id: check it with /api/reddit/dm/messages before sending again, or you may send it twice. Billed, like any send that reached Reddit. |
502 | kind: "recipient-unresolved": we could not look up to_username right now, even through your own session, so nothing was sent. Not billed. Retry, or pass to_user_t2. |
500 | Unexpected server error |
A DM Reddit refused is billed at this endpoint's price, including a refusal caused by the sender or the recipient: a recipient that does not accept chat requests (403), a sender account flagged by Reddit, or a recipient that does not exist (404). Not billed: recipient-unresolved (above), a 429 from this API (your key's own rate limit), a 503 (our capacity) and a 500 (our own failure).
Independent third-party API for developers and researchers. Not affiliated with, endorsed by, or sponsored by Reddit, Inc.
VoteNew
Upvote, downvote, or clear your vote on any Reddit post or comment via a single HTTP call, auto-detects whether the target is a post or comment for you.
List DM ThreadsNew
List the account's direct-message conversations and chat sidebar, newest activity first, with full thread metadata, last message, and unread count.
