Quick start

Send your first message

This tutorial walks you through sending your first DM using the Inbox API. You’ll learn the core workflow: authenticate, find an account, locate or create a thread, and send a message.

Before starting, make sure you have an API token. See the Authentication guide to get one.

Prerequisites

npm install axios

Set your API token as an environment variable:

export INBOX_API_TOKEN="your_token_here"

Step 1: Verify authentication

Confirm your API token works by fetching your team information:

import axios from "axios";

const client = axios.create({
  baseURL: "https://inboxapp.com/api/v1",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_API_TOKEN}`,
    "Content-Type": "application/json",
  },
});

const { data: team } = await client.get("/team");
console.log("Connected to team:", team.name);

const axios = require("axios");

const client = axios.create({
  baseURL: "https://inboxapp.com/api/v1",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_API_TOKEN}`,
    "Content-Type": "application/json",
  },
});

const { data: team } = await client.get("/team");
console.log("Connected to team:", team.name);

curl https://inboxapp.com/api/v1/team \
  -H "Authorization: Bearer $INBOX_API_TOKEN"

Response:

{
  "id": "hzcai5t59nn9vsck3rbuepyg",
  "name": "Acme Corp",
  "slug": "acme-corp",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": null,
  "currency": "USD",
  "allowSupportAccess": false
}

Step 2: List your account links

Account links are X accounts connected to your team. You need one to send messages:

const { data: accountLinks } = await client.get("/account-links");
console.log(`Found ${accountLinks.length} account(s)`);

const account = accountLinks[0];
console.log(`Using account: @${account.username}`);

Response:

[
  {
    "id": "df6jbw4h36qm5d9iu2sgn7kx",
    "platform": "twitter",
    "platformId": "1566123362161725440",
    "name": "Acme Corp",
    "username": "acmecorp",
    "image": "https://pbs.twimg.com/profile_images/...",
    "createdAt": "2024-06-01T12:00:00.000Z",
    "status": "active",
    "syncedAt": "2025-01-15T10:30:00.000Z"
  }
]

Step 3: Find or create a thread

Option A: Lookup an existing thread

If you know the prospect’s X user ID:

const { data: thread } = await client.get("/threads/lookup", {
  params: {
    externalPlatformId: "1876543210987654321",
    accountLinkId: account.id,
  },
});

if (thread) {
  console.log("Found existing thread:", thread.id);
} else {
  console.log("No thread exists yet");
}

Option B: Create a new thread

const { data: thread } = await client.post("/threads", {
  externalPlatformId: "1876543210987654321",
  accountLinkId: account.id,
});

console.log("Created thread:", thread.id);

Creating a thread doesn’t send a message. Use the messages endpoint to send a DM.

Step 4: Send a message

Replying to contacts who have already messaged you works on all plans. Sending the first message to a new contact requires the Outbound Messages addon on a paid plan. See Working with messages for details.

const { data: message } = await client.post(`/threads/${thread.id}/messages`, {
  content: "Hello! Thanks for reaching out.",
});

console.log("Message sent:", message.id);

Response:

{
  "id": "p8rvk2m5j0xn4wq7ybftcael",
  "platform": "twitter",
  "platformId": "1876543210987654322",
  "threadId": "l44e15irdq4db30i77cgphhx",
  "teamId": "hzcai5t59nn9vsck3rbuepyg",
  "authorId": "df6jbw4h36qm5d9iu2sgn7kx",
  "userId": "r3km7xj9wq5p2bvnhfdteoly",
  "campaignId": null,
  "content": "Hello! Thanks for reaching out.",
  "origin": "api",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "updatedAt": null,
  "isEdited": false,
  "entities": null,
  "attachment": null,
  "reactions": [],
  "replyData": null,
  "forwardData": null
}

Complete example

import axios from "axios";

const client = axios.create({
  baseURL: "https://inboxapp.com/api/v1",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_API_TOKEN}`,
    "Content-Type": "application/json",
  },
});

async function sendFirstMessage(
  prospectPlatformId: string,
  messageContent: string,
) {
  // 1. Verify authentication
  const { data: team } = await client.get("/team");
  console.log("Connected to:", team.name);

  // 2. Get account link
  const { data: accountLinks } = await client.get("/account-links");
  const account = accountLinks[0];
  console.log(`Using account: @${account.username}`);

  // 3. Lookup or create thread
  let thread;

  const { data: existing } = await client.get("/threads/lookup", {
    params: {
      externalPlatformId: prospectPlatformId,
      accountLinkId: account.id,
    },
  });

  if (existing) {
    thread = existing;
    console.log("Found existing thread");
  } else {
    const { data: created } = await client.post("/threads", {
      externalPlatformId: prospectPlatformId,
      accountLinkId: account.id,
    });
    thread = created;
    console.log("Created new thread");
  }

  // 4. Send message
  const { data: message } = await client.post(
    `/threads/${thread.id}/messages`,
    { content: messageContent },
  );

  console.log("Message sent:", message.id);
  return message;
}

sendFirstMessage("1876543210987654321", "Hello from the API!").catch((error) =>
  console.error("Error:", error.response?.data ?? error.message),
);

const axios = require("axios");

const client = axios.create({
  baseURL: "https://inboxapp.com/api/v1",
  headers: {
    Authorization: `Bearer ${process.env.INBOX_API_TOKEN}`,
    "Content-Type": "application/json",
  },
});

async function sendFirstMessage(prospectPlatformId, messageContent) {
  // 1. Verify authentication
  const { data: team } = await client.get("/team");
  console.log("Connected to:", team.name);

  // 2. Get account link
  const { data: accountLinks } = await client.get("/account-links");
  const account = accountLinks[0];
  console.log(`Using account: @${account.username}`);

  // 3. Lookup or create thread
  let thread;

  const { data: existing } = await client.get("/threads/lookup", {
    params: {
      externalPlatformId: prospectPlatformId,
      accountLinkId: account.id,
    },
  });

  if (existing) {
    thread = existing;
    console.log("Found existing thread");
  } else {
    const { data: created } = await client.post("/threads", {
      externalPlatformId: prospectPlatformId,
      accountLinkId: account.id,
    });
    thread = created;
    console.log("Created new thread");
  }

  // 4. Send message
  const { data: message } = await client.post(
    `/threads/${thread.id}/messages`,
    { content: messageContent },
  );

  console.log("Message sent:", message.id);
  return message;
}

sendFirstMessage("1876543210987654321", "Hello from the API!").catch((error) =>
  console.error("Error:", error.response?.data ?? error.message),
);

# 1. Get account links
curl https://inboxapp.com/api/v1/account-links \
  -H "Authorization: Bearer $INBOX_API_TOKEN"

# 2. Lookup thread (replace PLATFORM_ID and ACCOUNT_LINK_ID)
curl "https://inboxapp.com/api/v1/threads/lookup?externalPlatformId=1876543210987654321&accountLinkId=ACCOUNT_LINK_ID" \
  -H "Authorization: Bearer $INBOX_API_TOKEN"

# 3. Create thread if needed
curl -X POST https://inboxapp.com/api/v1/threads \
  -H "Authorization: Bearer $INBOX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"externalPlatformId": "1876543210987654321", "accountLinkId": "ACCOUNT_LINK_ID"}'

# 4. Send message (replace THREAD_ID)
curl -X POST "https://inboxapp.com/api/v1/threads/THREAD_ID/messages" \
  -H "Authorization: Bearer $INBOX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello from the API!"}'

Quick send alternative

For one-off messages, quick send combines thread lookup/creation and sending in one request:

const { data } = await client.post("/threads/messages", {
  externalPlatformId: "1876543210987654321",
  accountLinkId: account.id,
  content: "Hey, I saw your post and wanted to reach out!",
});

console.log("Message sent:", data.message.id);
console.log("Thread:", data.thread.id);

curl -X POST https://inboxapp.com/api/v1/threads/messages \
  -H "Authorization: Bearer $INBOX_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalPlatformId": "1876543210987654321",
    "accountLinkId": "df6jbw4h36qm5d9iu2sgn7kx",
    "content": "Hey, I saw your post and wanted to reach out!"
  }'

Response:

{
  "message": {
    "id": "p8rvk2m5j0xn4wq7ybftcael",
    "platform": "twitter",
    "threadId": "l44e15irdq4db30i77cgphhx",
    "content": "Hey, I saw your post and wanted to reach out!",
    "origin": "api",
    "createdAt": "2025-01-15T10:30:00.000Z"
  },
  "thread": {
    "id": "l44e15irdq4db30i77cgphhx",
    "platform": "twitter",
    "platformId": "1566123362161725440:1876543210987654321"
  }
}

Use quick send for simple scenarios. For more control over thread management, use the standard create/lookup + send workflow.

Next steps

Core concepts

Understand threads, prospects, and the data model

Managing threads

Learn thread operations and filtering

Working with prospects

Manage prospect data and context

Rate limits

Understand API limits

Getting started

Fundamentals

Configuration

Send your first message

Prerequisites

Step 1: Verify authentication

Step 2: List your account links

Step 3: Find or create a thread

Option A: Lookup an existing thread

Option B: Create a new thread

Step 4: Send a message

Complete example

Quick send alternative

Next steps

Core concepts

Managing threads

Working with prospects

Rate limits

​Send your first message

​Prerequisites

​Step 1: Verify authentication

​Step 2: List your account links

​Step 3: Find or create a thread

​Option A: Lookup an existing thread

​Option B: Create a new thread

​Step 4: Send a message

​Complete example

​Quick send alternative

​Next steps

Core concepts

Managing threads

Working with prospects

Rate limits

Send your first message

Prerequisites

Step 1: Verify authentication

Step 2: List your account links

Step 3: Find or create a thread

Option A: Lookup an existing thread

Option B: Create a new thread

Step 4: Send a message

Complete example

Quick send alternative

Next steps