Threads

Threads in Luella refer to the email conversations (or message chains) exchanged between a group of participants. Each thread includes all messages exchanged in that conversation. These are particularly useful for reading replies received for your outreach emails.

All references to mailboxId in this section refer to the email address ID, such as john.doe@luella.ai.

The thread model

This model describes metadata about a single thread, such as its participants, subject, teaser preview, and location (Inbox, Junk, Sent, Archive).

Properties

Name
threadId
Type
string
Description
Unique identifier for the thread.
Name
mailboxId
Type
string
Description
Email address (not mailbox resource) that owns the thread, e.g. john.doe@luella.ai.
Name
clusterId
Type
string
Description
(Optional) Cluster associated with this thread.
Name
sequenceId
Type
string
Description
(Optional) Sequence that initiated the outreach.
Name
campaignId
Type
string
Description
(Optional) Campaign associated with this conversation.
Name
subject
Type
string
Description
Email subject line for the thread.
Name
participants
Type
string[]
Description
List of participants in the thread (typically email addresses).
Name
location
Type
string
Description
Thread folder. One of: Inbox, Sent, Archive, Junk.
Name
teaser
Type
string
Description
A preview of the last message in the thread.
Name
status
Type
string
Description
Thread read status. One of: Read or Unread.
Name
lastMessageAt
Type
timestamp (ISO string)
Description
Timestamp of the last message in the thread.
Name
lastUpdatedAt
Type
timestamp (ISO string)
Description
Timestamp of last update to thread metadata.

POST/threads/ListThreads

List all threads

Retrieve a list of threads from one or more mailboxes, filtered by status, folder, or campaign context.

Required attributes

Name
userId
Type
string
Description
ID of the user making the request.
Name
workspaceId
Type
string
Description
Workspace containing the mailboxes.
Name
location
Type
string
Description
Thread folder to search in (Inbox, Junk, Sent, Archive).
Name
mailboxIds
Type
string[]
Description
Array of email address IDs (e.g. john.doe@luella.ai).
Name
sequenceIds
Type
string[]
Description
Optional filter for sequence IDs.
Name
campaignIds
Type
string[]
Description
Optional filter for campaign IDs.
Name
clusterIds
Type
string[]
Description
Optional filter for cluster IDs.
Name
status
Type
string[]
Description
One or more thread statuses (Read, Unread).
Name
sortOrder
Type
string
Description
Sort order (Ascending or Descending).

Optional attributes

Name
maxItems
Type
number
Description
Maximum threads to return.
Name
nextToken
Type
string
Description
Token for pagination.

Request

POST

/threads/ListThreads

{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "location": "Inbox",
  "mailboxIds": ["john.doe@luella.ai"],
  "sequenceIds": [],
  "campaignIds": [],
  "clusterIds": [],
  "status": ["Unread"],
  "sortOrder": "Descending",
  "maxItems": 10
}

Response

{
  "threads": [
    {
      "threadId": "thread_001",
      "mailboxId": "john.doe@luella.ai",
      "subject": "Re: Quick question",
      "participants": ["john.doe@luella.ai", "prospect@example.com"],
      "lastMessageAt": "2024-04-03T12:00:00.000Z",
      "location": "Inbox",
      "teaser": "Thanks for reaching out...",
      "status": "Unread"
    }
  ],
  "nextToken": null
}

POST/threads/GetThread

Get a thread

Retrieve all metadata about a specific thread, including mailbox, campaign, and participant information.

Required attributes

Name
userId
Type
string
Description
ID of the user requesting the thread.
Name
workspaceId
Type
string
Description
Workspace that owns the thread.
Name
threadId
Type
string
Description
Unique identifier for the thread to retrieve.

Request

POST

/threads/GetThread

{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "threadId": "thread_001"
}

Response

{
  "threadId": "thread_001",
  "mailboxId": "john.doe@luella.ai",
  "clusterId": "cluster_001",
  "sequenceId": "sequence_123",
  "campaignId": "camp_001",
  "subject": "Re: Meeting proposal",
  "participants": ["john.doe@luella.ai", "ceo@startup.com"],
  "lastMessageAt": "2024-04-02T16:00:00.000Z",
  "lastUpdatedAt": "2024-04-03T09:45:00.000Z",
  "location": "Inbox",
  "teaser": "Let's find a time next week...",
  "status": "Read"
}

POST/threads/UpdateThread

Update a thread

Update a thread’s metadata including location (Inbox, Sent, etc), read status, or teaser content. Use this to archive, mark read/unread, or move threads between folders.

Required attributes

Name
userId
Type
string
Description
ID of the user updating the thread.
Name
workspaceId
Type
string
Description
Workspace the thread belongs to.
Name
threadId
Type
string
Description
ID of the thread to update.
Name
participants
Type
string[]
Description
Updated list of participants.
Name
location
Type
string
Description
Updated folder location for the thread (Inbox, Sent, Archive, Junk).
Name
status
Type
string
Description
Updated thread status (Read or Unread).

Optional attributes

Name
subject
Type
string
Description
Optional subject line to override.
Name
teaser
Type
string
Description
Optional teaser/preview content.
Name
lastMessageAt
Type
timestamp (ISO string)
Description
Optional updated timestamp of the last message.

Request

POST

/threads/UpdateThread

{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "threadId": "thread_001",
  "participants": ["john.doe@luella.ai", "ceo@startup.com"],
  "location": "Archive",
  "status": "Read",
  "teaser": "Looking forward to your response",
  "lastMessageAt": "2024-04-03T16:00:00.000Z"
}

Response

{
  "threadId": "thread_001"
}

POST/threads/DeleteThread

Delete a thread

Permanently deletes a thread and all its metadata.

Required attributes

Name
userId
Type
string
Description
ID of the user performing the deletion.
Name
workspaceId
Type
string
Description
Workspace the thread belongs to.
Name
threadId
Type
string
Description
ID of the thread to delete.

Request

POST

/threads/DeleteThread

{
  "userId": "user_123",
  "workspaceId": "workspace_456",
  "threadId": "thread_001"
}

Response

{}