Skip to Content
Inbox Management API

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/json

The two sending endpoints (new-message and {uuid}/reply) are protected by extra middleware:

RuleBehavior
Paid workspace onlyOn 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 limit10 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 throttle10 requests per minute (429 when exceeded)
Plan inbox email limitIf 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

MethodEndpointDescription
GET/api/public-v1/inbox/conversation/allGet inbox conversations
POST/api/public-v1/inbox/conversation/new-messageSend a new email (creates a conversation)
POST/api/public-v1/inbox/conversation/{uuid}/replyReply to a conversation
POST/api/public-v1/inbox/conversation/{uuid}/assign-tagsSet the tags of a conversation
GET/api/public-v1/get-email-addressGet the inbox email address
GET/api/public-v1/inbox/assign-tagsList tags
POST/api/public-v1/inbox/assign-tagsCreate 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/all

Query Parameters

ParameterTypeRequiredDescription
folderstringNoinbox (default), sent, drafts, outbox, archive, trash, spam
itemintegerNoItems per page (default: 10). Use 0 to return all
pageintegerNoPage number
searchstringNoSearch 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

FieldDescription
created_atISO 8601 timestamp. When the thread has replies, this is the time of the latest reply
body_plainPlain text body, truncated to 200 characters. When the thread has replies, this is the latest reply’s body
replied_byUser who sent the latest reply (id, uuid, name, media, email), otherwise null
is_readtrue if the message was read
send_typetrue for messages sent from the workspace
tagsTags 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-message

See Authentication, Limits and Common Behavior for the paid-plan check, 10/day and 100/month limits, and throttling.

Request Body

FieldTypeRequiredDescription
subjectstringYesEmail subject
to_emailsarrayYes (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."}
messagestringNoMessage body (HTML supported)
ccstringNoComma-separated CC addresses
bccstringNoComma-separated BCC addresses
cc_emailsarrayNoCC addresses as an array (takes precedence over cc)
bcc_emailsarrayNoBCC addresses as an array (takes precedence over bcc)
from_emailstringNoSending address. Defaults to the workspace connected email
attachmentsarrayNoArray of objects with a media ID: [{"id": 12}]
draft_uuidstringNoUUID 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

StatusResponse
422Missing 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": "..."}
422Plan inbox email limit reached (upgrade_required: true)
429Daily/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}/reply

See Authentication, Limits and Common Behavior for the paid-plan check, 10/day and 100/month limits, and throttling.

Path Parameters

ParameterTypeRequiredDescription
uuidstringYesConversation UUID

Request Body

FieldTypeRequiredDescription
msgstringYesReply body (HTML supported)
typeintegerYes0 or 1. Required by validation; the reply logic does not use it
replyFromstringNoSending address. Defaults to the address the conversation was received on
to_emailsarrayNoReplaces the default recipient (the original Reply-To, or the sender)
cc / bccstringNoComma-separated addresses
cc_emails / bcc_emailsarrayNoAddresses as an array (take precedence over cc / bcc)
attachmentsarrayNoArray of objects with a media ID: [{"id": 12}]
schedule_timestringNoAccepted 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

StatusResponse
422Missing 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
422Plan inbox email limit reached (upgrade_required: true)
429Daily/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-tags

Path Parameters

ParameterTypeRequiredDescription
uuidstringYesConversation UUID

Request Body

FieldTypeRequiredDescription
tagsarray of integersNoIDs 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-address

Example 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-tags

Query Parameters

ParameterTypeRequiredDescription
itemintegerNoItems per page (default: 10). Use 0 to return all
pageintegerNoPage number
searchstringNoSearch 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-tags

Request Body

FieldTypeRequiredDescription
namestringYesTag name (max 191 characters)
colorstringNoTag 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

ParameterTypeRequiredDescription
idintegerYesTag ID to update

Request Body

FieldTypeRequiredDescription
namestringYesTag name (max 191 characters). Required for both PUT and PATCH
colorstringNoTag 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

ParameterTypeRequiredDescription
idintegerYesTag 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"}

Last updated on