RedditapisRedditapis
DM

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.

POST/api/reddit/dm$0.025 / call

Request Body

Cookies are passed as flat top-level fields (same shape as /comment and /vote).

FieldTypeRequiredDescription
to_usernamestringone ofTarget username (resolved internally to t2_xxx; when our lookup is refused, your own session is asked once before giving up)
to_user_t2stringone ofTarget t2_xxx ID directly, skips the username lookup, ~300ms faster
messagestringyesPlain-text DM body
reddit_sessionstringyesSession cookie from /api/reddit/login
loidstringyesLong-lived account identifier cookie
csrf_tokenstringyesAnti-CSRF cookie
proxyobject | stringnoSticky 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

StatusMeaning
400Missing 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
401Missing Bearer token
403Invalid Bearer token
403The 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.
404to_username names a Reddit account that does not exist or is suspended (kind: "recipient-not-found"). Nothing was sent.
502Could not send the DM, for example because the sender account is shadowbanned/spam-flagged
502delivery: "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.
502kind: "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.
500Unexpected 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.

On this page