ResourcesInbox

Inbox

Manage unified inbox contacts, call and email timelines, assistant mailboxes, threads, attachments, and Nylas events through the Talkturo API.

curl --request GET \
  --url "https://app.talkturo.com/api/inbox/list?accountSlug=acme&status=open&page=0" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example"

{
  "total": 1,
  "page": 0,
  "pageSize": 50,
  "contacts": [
    {
      "id": "cnt_7f3c9a21",
      "name": "Maya Patel",
      "email": "maya.patel@northstar.example",
      "phone": "+14155550182",
      "company": "Northstar Labs",
      "lastAt": "2025-02-14T16:20:00.000Z",
      "last": {
        "kind": "email",
        "channel": "email",
        "direction": "inbound",
        "ref": "msg_9a41",
        "preview": "Could we review the proposal?",
        "seconds": null,
        "assistant": "asst_2b7d"
      },
      "channels": ["email", "phone"],
      "assistants": [
        {
          "id": "asst_2b7d",
          "name": "Avery"
        }
      ],
      "unread": 2,
      "needsYou": true,
      "done": false,
      "assignee": null
    }
  ]
}

curl --request GET \
  --url "https://app.talkturo.com/api/inbox/contacts?q=maya%20patel&accountSlug=acme" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example"

{
  "contacts": [
    {
      "id": "cnt_7f3c9a21",
      "name": "Maya Patel",
      "email": "maya.patel@northstar.example",
      "company": "Northstar Labs"
    }
  ]
}

curl --request GET \
  --url "https://app.talkturo.com/api/inbox/contacts/cnt_7f3c9a21/timeline?accountSlug=acme&channel=email" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example"

{
  "contact": {
    "id": "cnt_7f3c9a21",
    "name": "Maya Patel",
    "firstName": "Maya",
    "lastName": "Patel",
    "email": "maya.patel@northstar.example",
    "phone": "+14155550182",
    "phoneSecondary": null,
    "company": "Northstar Labs",
    "jobTitle": "Operations Director",
    "leadStatus": "qualified",
    "source": "website",
    "createdAt": "2025-01-08T09:30:00.000Z",
    "lastAt": "2025-02-14T16:20:00.000Z",
    "lastChannel": "email",
    "lastAssistant": "Avery",
    "channelsUsed": ["email", "phone"],
    "done": false,
    "assignee": null,
    "groups": []
  },
  "items": [
    {
      "kind": "email",
      "id": "msg_9a41",
      "at": "2025-02-14T16:20:00.000Z",
      "channel": "email",
      "direction": "inbound",
      "assistantId": "asst_2b7d",
      "assistantName": "Avery",
      "threadId": "thr_41c8",
      "threadUnread": true,
      "sentBy": null,
      "fromName": "Maya Patel",
      "fromAddress": "maya.patel@northstar.example",
      "to": [{ "email": "avery@acme.example", "name": "Avery" }],
      "subject": "Proposal review",
      "text": "Could we review the proposal?",
      "deliveryStatus": "delivered",
      "deliveryDetail": null,
      "attachments": []
    }
  ],
  "mailboxes": [
    {
      "assistantId": "asst_2b7d",
      "assistantName": "Avery",
      "address": "avery@acme.example"
    }
  ]
}

curl --request POST \
  --url "https://app.talkturo.com/api/inbox/contact-state?accountSlug=acme" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example" \
  --header "Content-Type: application/json" \
  --data '{
    "contactIds": ["cnt_7f3c9a21"],
    "action": "assign",
    "assigneeId": "usr_84a1c2d9"
  }'

{
  "updated": 1
}

curl --request GET \
  --url "https://app.talkturo.com/api/inbox/access?accountSlug=acme" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example"

{
  "canManage": true,
  "me": "usr_84a1c2d9",
  "assistants": [
    { "id": "asst_2b7d", "name": "Avery" }
  ],
  "members": [
    {
      "id": "usr_84a1c2d9",
      "name": "Jordan Lee",
      "email": "jordan.lee@acme.example",
      "pictureUrl": null,
      "role": "manager",
      "manager": true,
      "assistantIds": null
    }
  ]
}

curl --request PUT \
  --url "https://app.talkturo.com/api/inbox/access?accountSlug=acme" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example" \
  --header "Content-Type: application/json" \
  --data '{
    "userId": "usr_84a1c2d9",
    "assistantIds": ["asst_2b7d"]
  }'

{
  "ok": true,
  "assistantIds": ["asst_2b7d"]
}

curl --request GET \
  --url "https://app.talkturo.com/api/inbox/members?accountSlug=acme" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example"

{
  "me": "usr_84a1c2d9",
  "members": [
    {
      "id": "usr_84a1c2d9",
      "name": "Jordan Lee",
      "email": "jordan.lee@acme.example",
      "pictureUrl": null,
      "role": "manager"
    }
  ]
}

curl --request GET \
  --url "https://app.talkturo.com/api/inbox/availability?localPart=avery&accountSlug=acme" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example"

{
  "ok": true,
  "address": "avery@acme.example"
}

curl --request GET \
  --url "https://app.talkturo.com/api/inbox/assistants/asst_2b7d/calls?accountSlug=acme&page=1&dir=inbound&via=web" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example"

{
  "calls": [
    {
      "id": "call_91d2",
      "direction": "inbound",
      "isWeb": true,
      "isTest": false,
      "status": "completed",
      "startedAt": "2025-02-14T15:00:00.000Z",
      "endedAt": "2025-02-14T15:08:12.000Z",
      "createdAt": "2025-02-14T15:08:14.000Z",
      "durationSeconds": 492,
      "counterpartNumber": "+14155550182",
      "ourNumber": null,
      "assistantName": "Avery",
      "contact": {
        "id": "cnt_7f3c9a21",
        "name": "Maya Patel",
        "company": "Northstar Labs"
      },
      "summary": "Reviewed implementation timeline."
    }
  ],
  "hasMore": false
}

curl --request GET \
  --url "https://app.talkturo.com/api/inbox/assistants/asst_2b7d/calls/call_91d2?accountSlug=acme" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example"

{
  "call": {
    "id": "call_91d2",
    "direction": "inbound",
    "isWeb": true,
    "isTest": false,
    "status": "completed",
    "startedAt": "2025-02-14T15:00:00.000Z",
    "endedAt": "2025-02-14T15:08:12.000Z",
    "createdAt": "2025-02-14T15:08:14.000Z",
    "durationSeconds": 492,
    "counterpartNumber": "+14155550182",
    "ourNumber": null,
    "assistantName": "Avery",
    "contact": null,
    "summary": "Reviewed implementation timeline.",
    "hasRecording": true,
    "messages": [
      {
        "role": "assistant",
        "message": "What would you like to review?",
        "time": 4
      }
    ]
  }
}

curl --request GET \
  --url "https://app.talkturo.com/api/inbox/assistants/asst_2b7d/calls/summary?accountSlug=acme" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example"

{
  "totals": {
    "calls": 42,
    "inbound": 27,
    "outbound": 15,
    "avgSeconds": 318
  },
  "numbers": [
    {
      "number": "+14155550182",
      "kind": "phone",
      "calls": 42,
      "inbound": 27,
      "outbound": 15,
      "avgSeconds": 318,
      "lastCallAt": "2025-02-14T15:08:14.000Z",
      "assigned": true
    }
  ]
}

curl --request GET \
  --url "https://app.talkturo.com/api/inbox/assistants/asst_2b7d/mailbox?accountSlug=acme" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example"

{
  "emailEnabled": true,
  "pricing": {
    "perMailboxMonth": 12,
    "perThousandEmails": 4
  },
  "domain": "acme.example",
  "suggestion": "avery",
  "mailbox": {
    "id": "mbx_51c9",
    "address": "avery@acme.example",
    "senderName": "Avery",
    "createdAt": "2025-02-01T10:00:00.000Z",
    "unread": 3,
    "signaturePreview": "Regards, Avery",
    "defaultSenderName": "Talkturo",
    "defaultSignature": "Sent with Talkturo",
    "ownSenderName": null,
    "ownSignature": null
  }
}

curl --request POST \
  --url "https://app.talkturo.com/api/inbox/assistants/asst_2b7d/mailbox?accountSlug=acme" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example" \
  --header "Content-Type: application/json" \
  --data '{ "localPart": "avery" }'

{
  "mailbox": {
    "id": "mbx_51c9",
    "address": "avery@acme.example"
  }
}

curl --request PATCH \
  --url "https://app.talkturo.com/api/inbox/assistants/asst_2b7d/mailbox?accountSlug=acme" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example" \
  --header "Content-Type: application/json" \
  --data '{
    "senderName": "Avery from Acme",
    "signature": "Regards,
Avery"
  }'

{
  "ok": true
}

curl --request DELETE \
  --url "https://app.talkturo.com/api/inbox/assistants/asst_2b7d/mailbox?accountSlug=acme" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example"

{
  "ok": true
}

curl --request POST \
  --url "https://app.talkturo.com/api/inbox/assistants/asst_2b7d/send?accountSlug=acme" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example" \
  --form 'payload={"mode":"new","to":[{"email":"maya.patel@northstar.example","name":"Maya Patel"}],"cc":[],"bcc":[],"subject":"Proposal review","text":"Could we schedule a review this week?","locale":"en"}' \
  --form "files=@proposal.pdf"

{
  "ok": true,
  "id": "msg_9a41",
  "threadId": "thr_41c8"
}

curl --request GET \
  --url "https://app.talkturo.com/api/inbox/assistants/asst_2b7d/threads?accountSlug=acme&folder=inbox" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example"

{
  "threads": [
    {
      "id": "thr_41c8",
      "subject": "Proposal review",
      "with": "Maya Patel",
      "withEmail": "maya.patel@northstar.example",
      "unread": true,
      "messageCount": 4,
      "hasAttachments": true,
      "deliveryProblem": false,
      "lastMessageAt": "2025-02-14T16:20:00.000Z",
      "lastDirection": "inbound",
      "preview": "Could we review the proposal?"
    }
  ]
}

curl --request POST \
  --url "https://app.talkturo.com/api/inbox/assistants/asst_2b7d/threads/thr_41c8/block?accountSlug=acme" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example" \
  --header "Content-Type: application/json" \
  --data '{ "domain": true }'

{
  "ok": true,
  "pattern": "@northstar.example"
}

curl --request DELETE \
  --url "https://app.talkturo.com/api/inbox/assistants/asst_2b7d/threads/thr_41c8/block?accountSlug=acme&domain=1" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example"

{
  "ok": true
}

curl --request POST \
  --url "https://app.talkturo.com/api/inbox/assistants/asst_2b7d/threads/thr_41c8/folder?accountSlug=acme" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example" \
  --header "Content-Type: application/json" \
  --data '{ "folder": "inbox" }'

{
  "ok": true,
  "folder": "inbox",
  "contactId": "cnt_7f3c9a21"
}

curl --request GET \
  --url "https://app.talkturo.com/api/inbox/threads/thr_41c8?accountSlug=acme" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example"

{
  "thread": {
    "id": "thr_41c8",
    "subject": "Proposal review",
    "mailboxAddress": "avery@acme.example",
    "deliveryProblem": false
  },
  "messages": [
    {
      "id": "msg_9a41",
      "direction": "inbound",
      "sentBy": null,
      "fromName": "Maya Patel",
      "fromAddress": "maya.patel@northstar.example",
      "to": [{ "email": "avery@acme.example", "name": "Avery" }],
      "cc": [],
      "replyTo": [],
      "subject": "Proposal review",
      "text": "Could we review the proposal?",
      "quotedText": "",
      "html": null,
      "inline": [],
      "deliveryStatus": "delivered",
      "deliveryDetail": null,
      "sentAt": "2025-02-14T16:20:00.000Z",
      "attachments": []
    }
  ]
}

curl --request POST \
  --url "https://app.talkturo.com/api/inbox/threads/thr_41c8?accountSlug=acme" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example" \
  --header "Content-Type: application/json" \
  --data '{ "action": "read" }'

{
  "ok": true
}

curl --request GET \
  --url "https://app.talkturo.com/api/inbox/attachments/att_6d21?accountSlug=acme" \
  --header "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example"

{
  "url": "https://storage.example/signed/att_6d21?expires=1739550060"
}

curl --request GET \
  --url "https://app.talkturo.com/api/inbox/nylas/webhook?challenge=challenge_8f4c"

challenge_8f4c

curl --request POST \
  --url "https://app.talkturo.com/api/inbox/nylas/webhook" \
  --header "Content-Type: application/json" \
  --header "X-Nylas-Signature: 7f4b9c8d2a6e1f0c4b8d7a9e3c2f1a6b5d4e8f9c0a1b2c3d4e5f60718293a4b5c" \
  --data '{
    "event": "message.created",
    "data": {
      "id": "msg_9a41"
    }
  }'

{
  "ok": true
}

Overview

Manage inbox contacts, review call and email timelines, send emails, configure assistant mailboxes, organize threads, download attachments, and process Nylas events through the Inbox API.

All Inbox endpoints except the Nylas webhook require session authentication. Use an authenticated Supabase browser session or a bearer session token. API key authentication is rejected with HTTP 403 and the error Not available with an API key.

Include accountSlug with bearer-session requests. Cookie-based browser requests can use accountSlug or teamId to select the workspace.

Endpoint summary

MethodPathPurpose
GET/api/inbox/listList and filter inbox contacts
GET/api/inbox/contactsSearch contacts
GET/api/inbox/contacts/{contactId}/timelineRetrieve a contact's call and email timeline
POST/api/inbox/contact-stateAssign, unassign, complete, or reopen contacts
GET/api/inbox/accessRead inbox access settings
PUT/api/inbox/accessUpdate assistant access restrictions
GET/api/inbox/membersList workspace members
GET/api/inbox/availabilityCheck an assistant mailbox address
GET/api/inbox/assistants/{assistantId}/callsList calls for an assistant
GET/api/inbox/assistants/{assistantId}/calls/{callId}Retrieve call details and transcript
GET/api/inbox/assistants/{assistantId}/calls/summarySummarize assistant call activity
GET/api/inbox/assistants/{assistantId}/mailboxRetrieve mailbox details
POST/api/inbox/assistants/{assistantId}/mailboxCreate a mailbox
PATCH/api/inbox/assistants/{assistantId}/mailboxUpdate mailbox sender settings
DELETE/api/inbox/assistants/{assistantId}/mailboxRemove a mailbox
POST/api/inbox/assistants/{assistantId}/sendSend an email
GET/api/inbox/assistants/{assistantId}/threadsList assistant email threads
POST/api/inbox/assistants/{assistantId}/threads/{threadId}/blockBlock a sender or domain
DELETE/api/inbox/assistants/{assistantId}/threads/{threadId}/blockRemove a sender or domain block
POST/api/inbox/assistants/{assistantId}/threads/{threadId}/folderMove a thread between inbox and spam
GET/api/inbox/threads/{threadId}Retrieve thread messages
POST/api/inbox/threads/{threadId}Mark a thread as read
GET/api/inbox/attachments/{attachmentId}Retrieve a signed attachment URL
GET/api/inbox/nylas/webhookComplete the Nylas webhook challenge
POST/api/inbox/nylas/webhookReceive Nylas events

Inbox list

GET /api/inbox/list

Retrieve a paginated list of inbox contacts. The default status filter is open, and each page contains up to 50 contacts.

query
accountSlugstring
Required

Workspace slug used to select the account.

query
assistantsstring

Comma-separated assistant UUIDs.

query
channelstring

Limit results to a communication channel.

Allowed values:phonewebemail
query
qstring

Search text, trimmed and limited to 100 characters.

query
unreadstring

Set to 1 to return only contacts with unread activity.

Allowed values:1
query
statusstring

Contact status. Omitted or unrecognized values use open.

Allowed values:opendoneall
query
assignedstring

Use me, unassigned, or a member UUID. Invalid values do not apply an assignment filter.

query
needsstring

Set to 1 to return contacts needing the current user.

Allowed values:1
query
pageinteger

Zero-based page number, clamped to the range 0 through 1000.

totalinteger
Required

Total contacts matching the filters.

pageinteger
Required

The returned zero-based page number.

pageSizeinteger
Required

Maximum number of contacts in a page. This value is 50.

contactsarray
Required

Contacts with their latest interaction, channels, assistants, unread count, completion state, and assignee.

A failed inbox query returns HTTP 500 with Could not load the Inbox.

GET /api/inbox/contacts

Search contacts by name, email, or company. Results require a non-empty email address and are limited to eight contacts.

query
qstring
Required

Search text. Special characters are removed, the value is trimmed, and the result is limited to 60 characters. Queries shorter than two characters return an empty result.

query
accountSlugstring
Required

Workspace slug used to select the account.

contactsarray
Required

Up to eight contacts with non-null email addresses.

A search query shorter than two characters returns contacts: [] without querying the database.

Contact timeline

GET /api/inbox/contacts/{contactId}/timeline

Retrieve a contact's profile, calls, emails, and available assistant mailboxes. Timeline items are sorted oldest first.

query
accountSlugstring
Required

Workspace slug used to select the account.

query
assistantsstring

Comma-separated assistant UUIDs. Invalid IDs are ignored.

query
channelstring

Use phone for non-web calls, web for web calls, or email for email messages. Omit the parameter to include calls and emails.

Allowed values:phonewebemail
contactobject
Required

Contact profile, status, channel history, groups, and assignee.

itemsarray
Required

Call and email timeline items. The API loads at most 100 calls and 100 email messages per category.

mailboxesarray
Required

Assistant mailboxes associated with the contact's accessible activity.

Restricted members automatically receive only activity associated with assistants they are permitted to see. A contact with no accessible activity returns HTTP 404.

Contact state

POST /api/inbox/contact-state

Assign, unassign, complete, or reopen up to 200 contacts in one request.

query
accountSlugstring
Required

Workspace slug used to select the account.

body
contactIdsarray
Required

One to 200 contact UUIDs.

body
actionstring
Required

State operation to apply.

Allowed values:assignunassigndonereopen
body
assigneeIdstring

Workspace member UUID. Required when action is assign.

updatedinteger
Required

Number of in-scope contacts changed.

Contacts belonging to another workspace are silently excluded. If no valid, in-scope contacts remain, the API returns HTTP 404.

Inbox access

GET /api/inbox/access

Read the current user's inbox access scope and, when permitted, workspace member restrictions.

query
accountSlugstring
Required

Workspace slug used to select the account.

canManageboolean
Required

Whether the current member can manage inbox access.

mestring
Required

Current user UUID.

assistantsarray
Required

Assistants available in the workspace.

membersarray
Required

Members and their assistant restrictions. Non-managers receive only their own member entry.

PUT /api/inbox/access

Set or remove a member's assistant access restriction.

query
accountSlugstring
Required

Workspace slug used to select the account.

body
userIdstring
Required

Workspace member UUID.

body
assistantIdsarray
Required

Assistant UUIDs, up to 500 values. Use null to remove the restriction and [] to save an explicit empty restriction.

okboolean
Required

Indicates that the restriction was saved.

assistantIdsarray

Valid assistant UUIDs retained by the workspace.

Only authorized managers can update restrictions. You cannot assign restrictions to a manager, and assistant IDs outside the workspace are silently discarded.

Workspace members

GET /api/inbox/members

List workspace members available for inbox assignment.

query
accountSlugstring
Required

Workspace slug used to select the account.

mestring
Required

Current user UUID.

membersarray
Required

Workspace members with their profile and role information.

Address availability

GET /api/inbox/availability

Check whether a mailbox local part is available in the workspace domain.

query
localPartstring

Mailbox local part to check. Defaults to an empty string.

query
accountSlugstring
Required

Workspace slug used to select the account.

okboolean
Required

true when the address can be used.

addressstring

Available address, or the checked address when unavailable.

reasonstring

Reason for unavailability, such as taken.

Assistant calls

GET /api/inbox/assistants/{assistantId}/calls

List an assistant's calls with optional direction and number filters. Pages contain 30 calls.

query
accountSlugstring
Required

Workspace slug used to select the account.

query
pageinteger

One-based page number. Defaults to 1.

query
dirstring

Filter by call direction.

Allowed values:inboundoutbound
query
viastring

Use web for web calls. Otherwise provide one of the assistant's phone numbers.

callsarray
Required

Calls matching the filters.

hasMoreboolean
Required

Whether another page is available.

Assistant call detail

GET /api/inbox/assistants/{assistantId}/calls/{callId}

Retrieve call metadata and non-empty transcript messages from the assistant or user.

query
accountSlugstring
Required

Workspace slug used to select the account.

callobject
Required

Call metadata, contact, recording availability, summary, and transcript messages.

Assistant call summary

GET /api/inbox/assistants/{assistantId}/calls/summary

Retrieve aggregate call counts and per-number activity for an assistant.

query
accountSlugstring
Required

Workspace slug used to select the account.

totalsobject
Required

Aggregate call counts and average duration.

numbersarray
Required

Call statistics for assigned phone numbers and web calls.

Web calls have an empty number. Assigned phone numbers with no calls are included with zero counts and a null average duration.

Mailbox management

GET /api/inbox/assistants/{assistantId}/mailbox

Retrieve mailbox configuration, pricing, sender defaults, and unread count.

query
accountSlugstring
Required

Workspace slug used to select the account.

emailEnabledboolean
Required

Whether assistant email is enabled.

pricingobject

Mailbox and email pricing, or null when unavailable.

domainstring
Required

Workspace mailbox domain.

suggestionstring
Required

Suggested mailbox local part.

mailboxobject

Mailbox details, or null when no mailbox exists.

POST /api/inbox/assistants/{assistantId}/mailbox

Create an assistant mailbox.

query
accountSlugstring
Required

Workspace slug used to select the account.

body
localPartstring
Required

Mailbox local part, from 1 to 64 characters. The created address uses the workspace domain.

mailboxobject
Required

The newly created mailbox identifier and address.

PATCH /api/inbox/assistants/{assistantId}/mailbox

Update the mailbox sender name or signature.

query
accountSlugstring
Required

Workspace slug used to select the account.

body
senderNamestring

Custom sender name, trimmed and limited to 120 characters. An empty string restores the workspace default.

body
signaturestring

Custom signature, limited to 2,000 characters. An empty string restores the workspace default.

okboolean
Required

Indicates that the mailbox settings were updated.

DELETE /api/inbox/assistants/{assistantId}/mailbox

Remove an assistant mailbox. Only workspace owners can perform this operation.

query
accountSlugstring
Required

Workspace slug used to select the account.

okboolean
Required

Indicates that the mailbox was removed.

Mailbox removal is irreversible from the API. Confirm the assistant and workspace before sending this request.

Send email

POST /api/inbox/assistants/{assistantId}/send

Send a new email, reply, reply-all message, or forward using multipart form data.

query
accountSlugstring
Required

Workspace slug used to select the account.

body
payloadobject
Required

JSON string containing mode, recipients, subject, message text, and locale.

body
filesfile

Zero or more attachments. Combined upload size must remain within the message size limit.

okboolean
Required

Indicates that the email was accepted for sending.

idstring

Identifier returned by the send service when available.

threadIdstring

Thread identifier returned by the send service when available.

The API returns 409 no_mailbox when the assistant has no mailbox and 413 too_large when uploaded files exceed the combined message size limit.

Assistant threads

GET /api/inbox/assistants/{assistantId}/threads

List up to 50 email threads for an assistant.

query
accountSlugstring
Required

Workspace slug used to select the account.

query
folderstring

Mailbox folder. Defaults to inbox; unrecognized values also use inbox.

Allowed values:inboxsentspam
threadsarray
Required

Thread summaries. Returns an empty array when the assistant has no mailbox.

Block or unblock a thread sender

POST /api/inbox/assistants/{assistantId}/threads/{threadId}/block

Block the sender of a thread and move the thread to spam. Set domain to true to block the sender's entire domain.

path
threadIdstring
Required

Thread identifier.

query
accountSlugstring
Required

Workspace slug used to select the account.

body
domainboolean

When true, block the sender's domain. Otherwise block only the exact sender address.

okboolean
Required

Indicates that the block was created.

patternstring
Required

Blocked email address or domain pattern beginning with @.

DELETE /api/inbox/assistants/{assistantId}/threads/{threadId}/block

Remove an exact sender block or a domain block.

path
threadIdstring
Required

Thread identifier.

query
accountSlugstring
Required

Workspace slug used to select the account.

query
domainstring

Set to 1 to remove the domain block. Omit it to remove the exact address block.

Allowed values:1
okboolean
Required

Indicates that the block was removed.

Blocking changes future sender handling and moves the current thread to spam. Verify whether you need an address block or a domain block before creating it.

Move a thread

POST /api/inbox/assistants/{assistantId}/threads/{threadId}/folder

Move a thread between the inbox and spam folders.

path
threadIdstring
Required

Thread identifier.

query
accountSlugstring
Required

Workspace slug used to select the account.

body
folderstring
Required

Destination folder.

Allowed values:spaminbox
okboolean
Required

Indicates that the thread moved successfully.

folderstring
Required

Destination folder.

contactIdstring

Existing or newly resolved CRM contact UUID, or null.

Moving a spam thread back to the inbox may resolve or create a CRM contact from the first inbound sender.

Thread messages

GET /api/inbox/threads/{threadId}

Retrieve a thread and its non-draft messages in oldest-first order.

query
accountSlugstring
Required

Workspace slug used to select the account.

threadobject
Required

Thread identifier, subject, mailbox address, and delivery status.

messagesarray
Required

Messages ordered oldest first. Drafts are excluded, and quoted text is separated from the main text.

POST /api/inbox/threads/{threadId}

Mark inbound messages in a thread as read and set the conversation unread count to zero.

query
accountSlugstring
Required

Workspace slug used to select the account.

body
actionstring
Required

Set to read.

Allowed values:read
okboolean
Required

Indicates that the thread was marked as read.

Attachment download

GET /api/inbox/attachments/{attachmentId}

Retrieve a signed storage URL for a downloadable attachment. The signed URL remains valid for 60 seconds.

query
accountSlugstring
Required

Workspace slug used to select the account.

urlstring
Required

Signed storage URL configured to download the attachment using its stored filename.

The API returns 404 Not found when the attachment is blocked, unavailable, outside the workspace, or outside the member's assistant scope.

Nylas webhook

The Nylas webhook is the only Inbox route that does not use session authentication. Verify webhook requests with HMAC-SHA256 using the raw request body and NYLAS_INBOX_WEBHOOK_SECRET.

GET /api/inbox/nylas/webhook

Complete the Nylas webhook verification challenge.

query
challengestring
Required

Challenge value supplied by Nylas.

bodystring
Required

The exact challenge value as plain text.

The response uses Content-Type: text/plain and does not require an authorization header.

POST /api/inbox/nylas/webhook

Receive and process a signed Nylas event.

header
X-Nylas-Signaturestring
Required

Hexadecimal HMAC-SHA256 signature of the raw request body using NYLAS_INBOX_WEBHOOK_SECRET.

body
eventobject
Required

Raw JSON Nylas event payload.

okboolean
Required

Indicates that the event was accepted and processed.

Return HTTP 500 for processing failures so Nylas retries the event. Invalid signatures return 401, and invalid JSON returns 400.

Common authentication errors

StatusResponse
401{"error":"Unauthorized"}
401{"error":"Invalid session token"}
401{"error":"Authentication required"}
400{"error":"Account slug required"}
400{"error":"teamId or accountSlug query parameter or body field required"}
404{"error":"Account not found"}
403{"error":"Access denied"}
403{"error":"Not available with an API key"}

Assistants

Configure and manage the assistants that handle inbox calls and email.

CRM Contacts

Work with contact records that appear in inbox timelines and assignments.

Webhooks

Review webhook patterns and event delivery behavior across Talkturo.

Was this page helpful?