--- title: "Team inbox" description: "Every operation in this group: what it accepts, what it returns and the errors it can answer with." url: "https://nextmail.sh/docs/api/reference/team-inbox" area: "API" category: "Reference" --- # Team inbox Every operation in this group: what it accepts, what it returns and the errors it can answer with. ## Operations Work a shared address as a team: give a thread to one person, mark it done, and talk about it in comments the sender never sees. Done archives the thread for everyone, and a new reply brings it back to the inbox. Only people who can see a thread can be given it or mentioned on it: the workspace owner, members who reach every address, and members who hold its address or its domain. ### `GET /threads/{id}/team` Read who has a thread Who the thread is assigned to and who marked it done, how many comments it has, who else is writing a reply right now, and everyone who can see it, the people it can be given to or who can be mentioned on it. Requires the `threads:read` scope. - Scopes: `threads:read`. **Path parameters** - `id` (`string`, required): The thread, as `GET /threads` returns it. **Returns** - `200` `ThreadTeam`: The thread as the team sees it. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: TypeScript [`nextmail.threads.getTeam()`](https://nextmail.sh/docs/sdk/reference/threads#getTeam); Python [`threads.get_team()`](https://nextmail.sh/docs/python/reference/threads#getTeam); Ruby [`threads.get_team`](https://nextmail.sh/docs/ruby/reference/threads#getTeam); PHP [`threads->getTeam`](https://nextmail.sh/docs/php/reference/threads#getTeam); Go [`Threads.GetTeam`](https://nextmail.sh/docs/go/reference/threads#getTeam); Java [`threads().getTeam`](https://nextmail.sh/docs/java/reference/threads#getTeam); C# [`Threads.GetTeamAsync`](https://nextmail.sh/docs/csharp/reference/threads#getTeam); CLI [`nextmail threads get-team`](https://nextmail.sh/docs/cli/reference/threads#threads-get-team); MCP [`getThreadTeam`](https://nextmail.sh/docs/mcp/tools/team-inbox#getThreadTeam). ### `PUT /threads/{id}/assignee` Assign a thread Gives the thread to one person, who is emailed unless they assigned it to themselves. `assigneeId` has to be somebody who can see the thread, or the call is a 422 `invalid_parameter` on `assigneeId`. `null` leaves it with nobody. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The thread, as `GET /threads` returns it. **Request body** - `assigneeId` (`string`, required, nullable, 1 to 128 characters): The person to assign the thread to, or null to leave it with nobody. **Returns** - `200` `ThreadAssignment`: Who has the thread now. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: TypeScript [`nextmail.threads.assign()`](https://nextmail.sh/docs/sdk/reference/threads#assign); Python [`threads.assign()`](https://nextmail.sh/docs/python/reference/threads#assign); Ruby [`threads.assign`](https://nextmail.sh/docs/ruby/reference/threads#assign); PHP [`threads->assign`](https://nextmail.sh/docs/php/reference/threads#assign); Go [`Threads.Assign`](https://nextmail.sh/docs/go/reference/threads#assign); Java [`threads().assign`](https://nextmail.sh/docs/java/reference/threads#assign); C# [`Threads.AssignAsync`](https://nextmail.sh/docs/csharp/reference/threads#assign); CLI [`nextmail threads assign`](https://nextmail.sh/docs/cli/reference/threads#threads-assign); MCP [`assignThread`](https://nextmail.sh/docs/mcp/tools/team-inbox#assignThread). ### `DELETE /threads/{id}/assignee` Unassign a thread Leaves the thread with nobody. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The thread, as `GET /threads` returns it. **Returns** - `200` `ThreadAssignment`: The thread, assigned to nobody. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: TypeScript [`nextmail.threads.unassign()`](https://nextmail.sh/docs/sdk/reference/threads#unassign); Python [`threads.unassign()`](https://nextmail.sh/docs/python/reference/threads#unassign); Ruby [`threads.unassign`](https://nextmail.sh/docs/ruby/reference/threads#unassign); PHP [`threads->unassign`](https://nextmail.sh/docs/php/reference/threads#unassign); Go [`Threads.Unassign`](https://nextmail.sh/docs/go/reference/threads#unassign); Java [`threads().unassign`](https://nextmail.sh/docs/java/reference/threads#unassign); C# [`Threads.UnassignAsync`](https://nextmail.sh/docs/csharp/reference/threads#unassign); CLI [`nextmail threads unassign`](https://nextmail.sh/docs/cli/reference/threads#threads-unassign); MCP [`assignThread`](https://nextmail.sh/docs/mcp/tools/team-inbox#assignThread). ### `POST /threads/{id}/done` Mark a thread done Archives the thread for everyone and records who marked it done. A new reply brings it back to the inbox. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The thread, as `GET /threads` returns it. **Returns** - `200` `ThreadAssignment`: The thread, with who marked it done. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: TypeScript [`nextmail.threads.markDone()`](https://nextmail.sh/docs/sdk/reference/threads#markDone); Python [`threads.mark_done()`](https://nextmail.sh/docs/python/reference/threads#markDone); Ruby [`threads.mark_done`](https://nextmail.sh/docs/ruby/reference/threads#markDone); PHP [`threads->markDone`](https://nextmail.sh/docs/php/reference/threads#markDone); Go [`Threads.MarkDone`](https://nextmail.sh/docs/go/reference/threads#markDone); Java [`threads().markDone`](https://nextmail.sh/docs/java/reference/threads#markDone); C# [`Threads.MarkDoneAsync`](https://nextmail.sh/docs/csharp/reference/threads#markDone); CLI [`nextmail threads mark-done`](https://nextmail.sh/docs/cli/reference/threads#threads-mark-done); MCP [`markThreadsDone`](https://nextmail.sh/docs/mcp/tools/team-inbox#markThreadsDone). ### `POST /threads/{id}/reopen` Reopen a thread Moves a done thread back to the inbox for everyone. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The thread, as `GET /threads` returns it. **Returns** - `200` `ThreadAssignment`: The thread, open again. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: TypeScript [`nextmail.threads.reopen()`](https://nextmail.sh/docs/sdk/reference/threads#reopen); Python [`threads.reopen()`](https://nextmail.sh/docs/python/reference/threads#reopen); Ruby [`threads.reopen`](https://nextmail.sh/docs/ruby/reference/threads#reopen); PHP [`threads->reopen`](https://nextmail.sh/docs/php/reference/threads#reopen); Go [`Threads.Reopen`](https://nextmail.sh/docs/go/reference/threads#reopen); Java [`threads().reopen`](https://nextmail.sh/docs/java/reference/threads#reopen); C# [`Threads.ReopenAsync`](https://nextmail.sh/docs/csharp/reference/threads#reopen); CLI [`nextmail threads reopen`](https://nextmail.sh/docs/cli/reference/threads#threads-reopen); MCP [`reopenThreads`](https://nextmail.sh/docs/mcp/tools/team-inbox#reopenThreads). ### `GET /threads/{id}/comments` List the comments on a thread Oldest first. Comments are the team’s: everyone who can see the thread reads them, and the sender never does. Requires the `threads:read` scope. - Scopes: `threads:read`. **Path parameters** - `id` (`string`, required): The thread, as `GET /threads` returns it. **Returns** - `200` `ThreadCommentList`: Every comment on the thread, oldest first. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: TypeScript [`nextmail.threads.listComments()`](https://nextmail.sh/docs/sdk/reference/threads#listComments); Python [`threads.list_comments()`](https://nextmail.sh/docs/python/reference/threads#listComments); Ruby [`threads.list_comments`](https://nextmail.sh/docs/ruby/reference/threads#listComments); PHP [`threads->listComments`](https://nextmail.sh/docs/php/reference/threads#listComments); Go [`Threads.ListComments`](https://nextmail.sh/docs/go/reference/threads#listComments); Java [`threads().listComments`](https://nextmail.sh/docs/java/reference/threads#listComments); C# [`Threads.ListCommentsAsync`](https://nextmail.sh/docs/csharp/reference/threads#listComments); CLI [`nextmail threads list-comments`](https://nextmail.sh/docs/cli/reference/threads#threads-list-comments); MCP [`listThreadComments`](https://nextmail.sh/docs/mcp/tools/team-inbox#listThreadComments). ### `POST /threads/{id}/comments` Comment on a thread Adds a comment for the team. Everybody in `mentions` is emailed, and each has to be able to see the thread, or the call is a 422 `invalid_parameter` on `mentions`. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The thread, as `GET /threads` returns it. **Request body** - `body` (`string`, required, 1 to 10000 characters): What the comment says. The people on the thread see it; the sender never does. - `mentions` (`string[]`, up to 20 items, default `[]`): The ids of people the comment mentions. Each has to be able to see the thread, and each is emailed. **Returns** - `201` `ThreadComment`: The comment. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: TypeScript [`nextmail.threads.createComment()`](https://nextmail.sh/docs/sdk/reference/threads#createComment); Python [`threads.create_comment()`](https://nextmail.sh/docs/python/reference/threads#createComment); Ruby [`threads.create_comment`](https://nextmail.sh/docs/ruby/reference/threads#createComment); PHP [`threads->createComment`](https://nextmail.sh/docs/php/reference/threads#createComment); Go [`Threads.CreateComment`](https://nextmail.sh/docs/go/reference/threads#createComment); Java [`threads().createComment`](https://nextmail.sh/docs/java/reference/threads#createComment); C# [`Threads.CreateCommentAsync`](https://nextmail.sh/docs/csharp/reference/threads#createComment); CLI [`nextmail threads create-comment`](https://nextmail.sh/docs/cli/reference/threads#threads-create-comment); MCP [`addThreadComment`](https://nextmail.sh/docs/mcp/tools/team-inbox#addThreadComment). ### `PATCH /threads/{id}/comments/{commentId}` Change a comment Replaces its text and its mentions. Only its author can change it, and anybody newly mentioned is emailed. Someone else’s comment, or one on another thread, is a 404. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The thread, as `GET /threads` returns it. - `commentId` (`string`, required): The id of a comment on that thread. **Request body** - `body` (`string`, required, 1 to 10000 characters): What the comment says. The people on the thread see it; the sender never does. - `mentions` (`string[]`, up to 20 items, default `[]`): The ids of people the comment mentions. Each has to be able to see the thread, and each is emailed. **Returns** - `200` `ThreadComment`: The comment as it is now. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: TypeScript [`nextmail.threads.updateComment()`](https://nextmail.sh/docs/sdk/reference/threads#updateComment); Python [`threads.update_comment()`](https://nextmail.sh/docs/python/reference/threads#updateComment); Ruby [`threads.update_comment`](https://nextmail.sh/docs/ruby/reference/threads#updateComment); PHP [`threads->updateComment`](https://nextmail.sh/docs/php/reference/threads#updateComment); Go [`Threads.UpdateComment`](https://nextmail.sh/docs/go/reference/threads#updateComment); Java [`threads().updateComment`](https://nextmail.sh/docs/java/reference/threads#updateComment); C# [`Threads.UpdateCommentAsync`](https://nextmail.sh/docs/csharp/reference/threads#updateComment); CLI [`nextmail threads update-comment`](https://nextmail.sh/docs/cli/reference/threads#threads-update-comment); MCP [`updateThreadComment`](https://nextmail.sh/docs/mcp/tools/team-inbox#updateThreadComment). ### `DELETE /threads/{id}/comments/{commentId}` Delete a comment Its author can delete it, and so can the workspace owner. Gone for good. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The thread, as `GET /threads` returns it. - `commentId` (`string`, required): The id of a comment on that thread. **Returns** - `200` `DeletedThreadComment`: Deleted. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: TypeScript [`nextmail.threads.deleteComment()`](https://nextmail.sh/docs/sdk/reference/threads#deleteComment); Python [`threads.delete_comment()`](https://nextmail.sh/docs/python/reference/threads#deleteComment); Ruby [`threads.delete_comment`](https://nextmail.sh/docs/ruby/reference/threads#deleteComment); PHP [`threads->deleteComment`](https://nextmail.sh/docs/php/reference/threads#deleteComment); Go [`Threads.DeleteComment`](https://nextmail.sh/docs/go/reference/threads#deleteComment); Java [`threads().deleteComment`](https://nextmail.sh/docs/java/reference/threads#deleteComment); C# [`Threads.DeleteCommentAsync`](https://nextmail.sh/docs/csharp/reference/threads#deleteComment); CLI [`nextmail threads delete-comment`](https://nextmail.sh/docs/cli/reference/threads#threads-delete-comment); MCP [`deleteThreadComment`](https://nextmail.sh/docs/mcp/tools/team-inbox#deleteThreadComment). ### Objects #### `DeletedThreadComment` `object` - `object` (`string`, one of `"thread_comment"`) - `id` (`string`) - `threadId` (`string`) - `deleted` (`boolean`, one of `true`) #### `TeamMember` `object` - `object` (`string`, required, one of `"team_member"`) - `id` (`string`, required): Their user id, what `assigneeId` and `mentions` take. - `name` (`string`, required, nullable) - `email` (`string`, required) #### `ThreadAssignment` `object` - `object` (`string`, required, one of `"thread_assignment"`) - `threadId` (`string`, required) - `assignee` (`TeamMember`, required) - `assignedBy` (`TeamMember`, required) - `assignedAt` (`string`, required, nullable, format `date-time`) - `doneBy` (`TeamMember`, required) - `doneAt` (`string`, required, nullable, format `date-time`) #### `ThreadComment` `object` - `object` (`string`, required, one of `"thread_comment"`) - `id` (`string`, required) - `threadId` (`string`, required) - `author` (`TeamMember`, required) - `body` (`string`, required, up to 10000 characters) - `mentions` (`TeamMember[]`, required) - `createdAt` (`string`, required, format `date-time`) - `editedAt` (`string`, required, nullable, format `date-time`) #### `ThreadCommentList` `object` - `object` (`string`, one of `"list"`) - `data` (`ThreadComment[]`) #### `ThreadTeam` `object` - `object` (`string`, required, one of `"thread_team"`) - `threadId` (`string`, required) - `assignment` (`ThreadAssignment`, required) - `commentCount` (`integer`, required) - `replying` (`TeamMember[]`, required): Others writing a reply in the app in the last 30 seconds. - `team` (`TeamMember[]`, required): Everyone who can see the thread.