> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inboxapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick start

> Send your first DM in 5 minutes

## 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.

<Note>
  Before starting, make sure you have an API token. See the [Authentication
  guide](/configuration/authentication) to get one.
</Note>

## Prerequisites

```bash theme={null}
npm install axios
```

Set your API token as an environment variable:

```bash theme={null}
export INBOX_API_TOKEN="your_token_here"
```

## Step 1: Verify authentication

Confirm your API token works by fetching your team information:

<CodeGroup>
  ```typescript verify.ts theme={null}
  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);
  ```

  ```javascript verify.js theme={null}
  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);
  ```

  ```bash cURL theme={null}
  curl https://inboxapp.com/api/v1/team \
    -H "Authorization: Bearer $INBOX_API_TOKEN"
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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:

```typescript theme={null}
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:**

```json theme={null}
[
  {
    "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:

```typescript theme={null}
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

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

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

<Note>
  Creating a thread doesn't send a message. Use the [messages
  endpoint](/api-reference/messages/send-message) to send a DM.
</Note>

## Step 4: Send a message

<Note>
  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](/guides/messages#sending-messages) for details.
</Note>

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

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

**Response:**

```json theme={null}
{
  "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

<CodeGroup>
  ```typescript send-message.ts theme={null}
  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),
  );
  ```

  ```javascript send-message.js theme={null}
  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),
  );
  ```

  ```bash cURL theme={null}
  # 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!"}'
  ```
</CodeGroup>

## Quick send alternative

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

<CodeGroup>
  ```typescript quick-send.ts theme={null}
  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);
  ```

  ```bash cURL theme={null}
  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!"
    }'
  ```
</CodeGroup>

**Response:**

```json theme={null}
{
  "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"
  }
}
```

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

## Next steps

<CardGroup cols={2}>
  <Card title="Core concepts" icon="book" href="/guides/core-concepts">
    Understand threads, prospects, and the data model
  </Card>

  <Card title="Managing threads" icon="messages-square" href="/guides/managing-threads">
    Learn thread operations and filtering
  </Card>

  <Card title="Working with prospects" icon="user" href="/guides/prospects">
    Manage prospect data and context
  </Card>

  <Card title="Rate limits" icon="gauge" href="/reference/rate-limits">
    Understand API limits
  </Card>
</CardGroup>