Inbox Management API
The Inbox Management API provides comprehensive email conversation handling and communication management capabilities. This powerful API allows you to manage email threads, assign tags, reply to conversations, and organize your communication workflow efficiently.
Overview
Inbox Management consists of:
- Conversations: List inbox conversations (threads) by folder
- Messaging: Send a new email and reply to an existing conversation (queued for delivery)
- Tags: Create, list, update and delete inbox tags, and assign tags to conversations
- Inbox Address: Get the workspace inbox (forwarding / connected) email address
Authentication, Limits and Common Behavior
Every request must send the secret key header:
X-Secret-Key: your-secret-key-here
Content-Type: application/jsonThe two sending endpoints (new-message and {uuid}/reply) are protected by extra middleware:
| Rule | Behavior |
|---|---|
| Paid workspace only | On a non-paid workspace the request is not processed and the API responds 403 with {"success": false, "message": "Only paid users are allowed"} |
| Inbox email send limit | 10 requests per day and 100 per month per workspace (counted for the inbox type). Over the limit: 429 with {"success": false, "message": "Your workspace has exceeded the inbox email sending limit"} |
| Request throttle | 10 requests per minute (429 when exceeded) |
| Plan inbox email limit | If the plan’s inbox email limit is reached: 422 with {"status": 422, "msg": "...", "limit_info": {...}, "upgrade_required": true} |
Validation failures return 422 with {"error": {"field": ["message"]}}. Business-rule errors return 422 with {"error": {"msg": ["message"]}}, unless a section below shows a different shape.
Main Endpoints Overview
| Method | Endpoint | Description |
|---|---|---|
GET | /api/public-v1/inbox/conversation/all | Get inbox conversations |
POST | /api/public-v1/inbox/conversation/new-message | Send a new email (creates a conversation) |
POST | /api/public-v1/inbox/conversation/{uuid}/reply | Reply to a conversation |
POST | /api/public-v1/inbox/conversation/{uuid}/assign-tags | Set the tags of a conversation |
GET | /api/public-v1/get-email-address | Get the inbox email address |
GET | /api/public-v1/inbox/assign-tags | List tags |
POST | /api/public-v1/inbox/assign-tags | Create a tag |
PUT / PATCH | /api/public-v1/inbox/assign-tags/{id} | Update a tag |
DELETE | /api/public-v1/inbox/assign-tags/{id} | Delete a tag |
There is no GET /inbox/assign-tags/{id} (show) endpoint.
Get All Conversations
Retrieve conversations (root messages of each thread) for a folder, ordered by latest activity (newest first).
GET /api/public-v1/inbox/conversation/allQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
folder | string | No | inbox (default), sent, drafts, outbox, archive, trash, spam |
item | integer | No | Items per page (default: 10). Use 0 to return all |
page | integer | No | Page number |
search | string | No | Search term for conversations |
Results are limited to the mailboxes the secret key’s user is allowed to access.
Example Request
curl -X GET "https://public-api.taskip.net/api/public-v1/inbox/conversation/all?folder=inbox&item=20" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json"Example Response
{
"data": [
{
"message_id": "msg_abc123def456",
"in_reply_to": null,
"reply_to": "john.doe@client.com",
"from_email": "john.doe@client.com",
"from_name": "John Doe",
"to_email": "support@yourcompany.com",
"cc_emails": null,
"bcc_emails": null,
"subject": "Project Discussion - Website Redesign",
"is_read": false,
"created_at": "2024-01-15T10:30:00+00:00",
"uuid": "9c4a1f4e-6c1b-4b6e-9a55-0d6a1c7f2e11",
"body_plain": "Looking forward to the updated mockups and design concepts...",
"tags": [
{ "id": 1, "name": "Client Communication", "color": "blue" }
],
"replied_by": null,
"send_type": false,
"send_emails": null
}
],
"links": {
"first": "https://public-api.taskip.net/api/public-v1/inbox/conversation/all?page=1",
"last": "https://public-api.taskip.net/api/public-v1/inbox/conversation/all?page=3",
"prev": null,
"next": "https://public-api.taskip.net/api/public-v1/inbox/conversation/all?page=2"
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 3,
"path": "https://public-api.taskip.net/api/public-v1/inbox/conversation/all",
"per_page": 10,
"to": 10,
"total": 25
}
}Response Field Notes
| Field | Description |
|---|---|
created_at | ISO 8601 timestamp. When the thread has replies, this is the time of the latest reply |
body_plain | Plain text body, truncated to 200 characters. When the thread has replies, this is the latest reply’s body |
replied_by | User who sent the latest reply (id, uuid, name, media, email), otherwise null |
is_read | true if the message was read |
send_type | true for messages sent from the workspace |
tags | Tags attached to the conversation (id, name, color) |
Create New Message/Conversation
Send a new email. The message is queued for delivery. One conversation is created for each address in to_emails.
POST /api/public-v1/inbox/conversation/new-messageSee Authentication, Limits and Common Behavior for the paid-plan check, 10/day and 100/month limits, and throttling.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
subject | string | Yes | Email subject |
to_emails | array | Yes (in practice) | Recipient email addresses. Also accepts a comma-separated string or a JSON array string. It is not validated by the request class; if no valid recipient results, the API returns 422 {"msg": "No valid recipient addresses were provided."} |
message | string | No | Message body (HTML supported) |
cc | string | No | Comma-separated CC addresses |
bcc | string | No | Comma-separated BCC addresses |
cc_emails | array | No | CC addresses as an array (takes precedence over cc) |
bcc_emails | array | No | BCC addresses as an array (takes precedence over bcc) |
from_email | string | No | Sending address. Defaults to the workspace connected email |
attachments | array | No | Array of objects with a media ID: [{"id": 12}] |
draft_uuid | string | No | UUID of a draft (or failed outbox item) to send instead of creating a new conversation |
The sending address must have verified DNS and cannot be a platform default *.taskip.email address.
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/inbox/conversation/new-message" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"to_emails": ["client@example.com"],
"subject": "Project Update - Website Development",
"message": "<p>Hi there,</p><p>I wanted to provide you with an update...</p>",
"cc": "manager@taskip.com",
"bcc": "archive@taskip.com"
}'Example Response
Status 202 Accepted:
{
"data": {
"message_id": "0b2f8c9e-3a7d-4f5e-8b1c-6d4e2a9f7c10",
"in_reply_to": null,
"reply_to": "client@example.com",
"from_email": "support@yourcompany.com",
"from_name": "Your Company",
"to_email": "client@example.com",
"cc_emails": "manager@taskip.com",
"bcc_emails": "archive@taskip.com",
"subject": "Project Update - Website Development",
"is_read": true,
"created_at": "2024-01-15T10:30:00+00:00",
"uuid": "7e1d5a3c-2b4f-4c8a-9d6e-1f0a3b5c7d92",
"body_plain": "Hi there, I wanted to provide you with an update...",
"tags": [],
"replied_by": null,
"send_type": true,
"send_emails": null
},
"send_emails": ["client@example.com"],
"msg": "Email queued — you will be notified when it is sent"
}When several recipients are given, data is the last conversation created and send_emails lists every recipient.
Errors
| Status | Response |
|---|---|
422 | Missing subject: {"error": {"subject": ["The subject field is required."]}} |
422 | {"msg": "Workspace connected mail not found"} |
422 | {"msg": "...", "error_type": "dns_not_verified", "email": "...", "domain": "...", "action_required": "...", "help_url": "..."} |
422 | {"msg": "...", "error_type": "taskip_email_not_allowed", "email": "..."} |
422 | Plan inbox email limit reached (upgrade_required: true) |
429 | Daily/monthly send limit or per-minute throttle exceeded |
Reply to Conversation
Reply to an existing conversation. The reply is queued for delivery.
POST /api/public-v1/inbox/conversation/{uuid}/replySee Authentication, Limits and Common Behavior for the paid-plan check, 10/day and 100/month limits, and throttling.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
uuid | string | Yes | Conversation UUID |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
msg | string | Yes | Reply body (HTML supported) |
type | integer | Yes | 0 or 1. Required by validation; the reply logic does not use it |
replyFrom | string | No | Sending address. Defaults to the address the conversation was received on |
to_emails | array | No | Replaces the default recipient (the original Reply-To, or the sender) |
cc / bcc | string | No | Comma-separated addresses |
cc_emails / bcc_emails | array | No | Addresses as an array (take precedence over cc / bcc) |
attachments | array | No | Array of objects with a media ID: [{"id": 12}] |
schedule_time | string | No | Accepted by validation but not used by the reply logic |
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/inbox/conversation/9c4a1f4e-6c1b-4b6e-9a55-0d6a1c7f2e11/reply" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{
"msg": "<p>Thank you for your message. I will review and respond soon.</p>",
"type": 0
}'Example Response
Status 202 Accepted:
{
"data": {
"message_id": "5a9e3b7c-1d2f-4a6b-8c0e-9f1d3b5a7c24",
"in_reply_to": "msg_abc123def456",
"from_email": "support@yourcompany.com",
"from_name": "Your Company",
"to_email": "john.doe@client.com",
"cc_emails": null,
"bcc_emails": null,
"subject": "Re: Project Discussion - Website Redesign",
"is_read": true,
"delivered": false,
"created_at": "just now",
"uuid": "2c8d4f6a-0b1e-4d3c-9a5f-7e9b1d3f5a60",
"body_plain": "Thank you for your message. I will review and respond soon.",
"body_html": "<p>Thank you for your message. I will review and respond soon.</p>",
"error_message": null,
"attachments": [],
"reply_by": {
"id": 12,
"uuid": "user-uuid",
"name": "Jane Smith",
"media": null,
"email": "jane@taskip.com"
}
},
"msg": "Reply queued — you will be notified when it is sent"
}delivered becomes true only after the queued email is sent.
Errors
| Status | Response |
|---|---|
422 | Missing msg or type: {"error": {"msg": ["The msg field is required."]}} |
422 | {"error": {"msg": ["Conversation not found"]}} |
422 | {"error": {"msg": ["You do not have permission to access this conversation"]}} |
422 | {"msg": "...", "error_type": "no_reply_address"}, dns_not_verified, or taskip_email_not_allowed |
422 | Plan inbox email limit reached (upgrade_required: true) |
429 | Daily/monthly send limit or per-minute throttle exceeded |
Assign Tags to Conversation
Set the tags of a conversation. The submitted list replaces the conversation’s current tags. Send an empty list (or omit tags) to remove all tags.
POST /api/public-v1/inbox/conversation/{uuid}/assign-tagsPath Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
uuid | string | Yes | Conversation UUID |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
tags | array of integers | No | IDs of existing tags (see List Tags). An empty array or omitted field detaches all tags |
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/inbox/conversation/9c4a1f4e-6c1b-4b6e-9a55-0d6a1c7f2e11/assign-tags" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{ "tags": [1, 2] }'Example Response
{ "msg": "Tag assigned" }When all tags are removed: {"msg": "Tag detached"}.
Errors
404{"msg": "Conversation not found"}403{"msg": "You do not have permission to access this conversation"}
Get Email Address
Retrieve the workspace inbox email configuration. If the workspace has no inbox address yet, one is created; if creation fails the API returns 422 {"error": {"msg": ["Failed to create email address"]}}.
GET /api/public-v1/get-email-addressExample Request
curl -X GET "https://public-api.taskip.net/api/public-v1/get-email-address" \
-H "X-Secret-Key: your-secret-key-here"Example Response
{
"forwarding_email": "inbox-12345@example.com",
"connected_email": "support@yourcompany.com",
"verified_at": "2024-01-15T10:30:00.000000Z",
"forwarding_verified_at": "2024-01-15T11:00:00.000000Z",
"dns_verified_at": "2024-01-15T11:15:00.000000Z",
"from_name": "Your Company"
}List Tags
Retrieve inbox tags, newest first.
GET /api/public-v1/inbox/assign-tagsQuery Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
item | integer | No | Items per page (default: 10). Use 0 to return all |
page | integer | No | Page number |
search | string | No | Search by tag name |
Example Request
curl -X GET "https://public-api.taskip.net/api/public-v1/inbox/assign-tags?item=0" \
-H "X-Secret-Key: your-secret-key-here"Example Response
{
"data": [
{ "id": 2, "name": "High Priority", "color": "red" },
{ "id": 1, "name": "Client Communication", "color": "blue" }
],
"links": {
"first": "https://public-api.taskip.net/api/public-v1/inbox/assign-tags?page=1",
"last": "https://public-api.taskip.net/api/public-v1/inbox/assign-tags?page=1",
"prev": null,
"next": null
},
"meta": {
"current_page": 1,
"from": 1,
"last_page": 1,
"per_page": 10,
"to": 2,
"total": 2
}
}With item=0 the response contains only data (no pagination).
Create a Tag
POST /api/public-v1/inbox/assign-tagsRequest Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Tag name (max 191 characters) |
color | string | No | Tag color (max 98 characters) |
Example Request
curl -X POST "https://public-api.taskip.net/api/public-v1/inbox/assign-tags" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{ "name": "Client Communication", "color": "blue" }'Example Response
{
"msg": "Tag added successfully",
"tag": { "id": 3, "name": "Client Communication", "color": "blue" }
}Errors
422{"error": {"name": ["The name field is required."]}}
Update a Tag
PUT /api/public-v1/inbox/assign-tags/{id}
PATCH /api/public-v1/inbox/assign-tags/{id}Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Tag ID to update |
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Tag name (max 191 characters). Required for both PUT and PATCH |
color | string | No | Tag color (max 98 characters) |
Example Request
curl -X PUT "https://public-api.taskip.net/api/public-v1/inbox/assign-tags/1" \
-H "X-Secret-Key: your-secret-key-here" \
-H "Content-Type: application/json" \
-d '{ "name": "Updated Client Communication", "color": "green" }'Example Response
{ "msg": "Tag updated successfully" }Errors
404{"msg": "Tag not found"}422{"error": {"name": ["The name field is required."]}}
Delete a Tag
DELETE /api/public-v1/inbox/assign-tags/{id}Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | integer | Yes | Tag ID to delete |
Example Request
curl -X DELETE "https://public-api.taskip.net/api/public-v1/inbox/assign-tags/1" \
-H "X-Secret-Key: your-secret-key-here"Example Response
{ "msg": "Tag deleted successfully" }Errors
404{"msg": "Tag not found"}