# Inbox Inbox items are created when external services send data through the [[API-Reference/Webhooks|webhook endpoint]]. Items arrive as pending, and you can review them, convert them to Zaphiri tasks or dismiss them. > [!quote] Your triage queue for external items > The Inbox is a staging area. Items arrive from integrations, and you decide what becomes a task and what gets dismissed. All Inbox endpoints require [[API-Reference/Authentication|JWT authentication]]. --- ## The Inbox Item Object ```json { "id": "537059f9-5f06-44c7-9098-7b72b5cc629e", "integration_id": "7de5dbca-a75d-485c-989e-ddc17b30192f", "user_id": "7f703dd2-4b68-4118-803e-9618d22f2578", "title": "Sprint Backlog Import", "body": "Fix login redirect bug", "source": "jira", "external_id": "PROJ-142", "metadata": {"sprint": "2026-Q1-3"}, "resolved_date": "2026-02-18", "resolved_label": "imported", "resolved_project": null, "resolved_estimated_minutes": 15, "resolved_energy": "medium", "resolved_priority": "medium", "status": "pending", "received_at": "2026-02-18T18:15:30Z", "processed_at": null } ``` ### Fields | Field | Type | Description | |-------|------|-------------| | `id` | UUID | Unique inbox item identifier | | `integration_id` | UUID | The integration that created this item | | `user_id` | UUID | Owner's user ID | | `title` | string or null | Batch title from the webhook request | | `body` | string or null | Item text content | | `source` | string or null | Source identifier (for example `"github"`, `"todoist"`) | | `external_id` | string or null | External system ID (used for deduplication) | | `metadata` | object or null | Arbitrary JSON metadata from the webhook request | | `resolved_date` | string or null | Computed date in `YYYY-MM-DD` format (from template config or override) | | `resolved_label` | string or null | Computed label (from template config or override) | | `resolved_project` | string or null | Computed project (from template config or override) | | `resolved_estimated_minutes` | integer or null | Computed time estimate in minutes | | `resolved_energy` | string or null | Computed energy level: `"low"`, `"medium"`, or `"high"` | | `resolved_priority` | string or null | Computed priority: `"low"`, `"medium"`, `"high"`, or `"urgent"` | | `status` | string | Item status: `"pending"`, `"converted"`, or `"dismissed"` | | `task_id` | UUID (only present when converted) | Zaphiri task ID if the item has been converted. This field is omitted when the item has not been converted. | | `received_at` | datetime | When the item was created (ISO 8601) | | `processed_at` | datetime or null | When the item was converted or dismissed (ISO 8601) | ### Item Status Lifecycle ``` pending → converted (item became a Zaphiri task) pending → dismissed (item was discarded) ``` Items cannot be reverted once converted or dismissed. --- ## List Pending Items Returns Inbox items with `status: "pending"` for the authenticated account, ordered by received date (newest first). ``` GET /api/v1/inbox ``` ### Headers | Header | Required | Value | |--------|----------|-------| | `Authorization` | Yes | `Bearer <jwt>` | ### Query Parameters | Parameter | Type | Default | Max | Description | |-----------|------|---------|-----|-------------| | `limit` | integer | 50 | 100 | Number of items to return | | `offset` | integer | 0 | - | Number of items to skip | ### Response `200 OK` ```json [ { "id": "537059f9-5f06-44c7-9098-7b72b5cc629e", "integration_id": "7de5dbca-a75d-485c-989e-ddc17b30192f", "user_id": "7f703dd2-4b68-4118-803e-9618d22f2578", "body": "Fix login redirect bug", "source": "jira", "external_id": "PROJ-142", "resolved_date": "2026-02-18", "resolved_label": "imported", "resolved_priority": "medium", "status": "pending", "received_at": "2026-02-18T18:15:30Z" } ] ``` Returns an empty array `[]` if no pending items exist. ### curl ```bash curl -X GET "https://tickup-api.mytickup.com/api/v1/inbox?limit=20&offset=0" \ -H "Authorization: Bearer <jwt>" ``` --- ## Convert Item Converts a pending Inbox item into a Zaphiri task. The item's resolved values (date, label, priority, energy and so on) are applied to the new task. ``` POST /api/v1/inbox/{id}/convert ``` ### Path Parameters | Parameter | Type | Description | |-----------|------|-------------| | `id` | UUID | Inbox item ID | ### Headers | Header | Required | Value | |--------|----------|-------| | `Authorization` | Yes | `Bearer <jwt>` | ### Response `200 OK` Returns the updated Inbox item with `status: "converted"` and the new `task_id`: ```json { "id": "537059f9-5f06-44c7-9098-7b72b5cc629e", "integration_id": "7de5dbca-a75d-485c-989e-ddc17b30192f", "user_id": "7f703dd2-4b68-4118-803e-9618d22f2578", "body": "Fix login redirect bug", "source": "jira", "status": "converted", "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "received_at": "2026-02-18T18:15:30Z", "processed_at": "2026-02-18T19:30:00Z" } ``` ### Task Creation Details When an item is converted, a task is created in the main Zaphiri app with these mappings: | Inbox Item Field | Zaphiri Task Field | |------------------|-------------------| | `title` or `body` (first 100 chars) | Task name | | `body` | Task description | | `resolved_priority` | Priority (`"medium"` maps to `"normal"`) | | `resolved_energy` | Energy (`"low"` → `"recharge"`, `"medium"` → `"steady"`, `"high"` → `"peak"`) | | `resolved_date` | Panel date | ### Errors | Code | Error | Cause | |------|-------|-------| | `400` | `invalid item ID` | Path parameter is not a valid UUID | | `400` | `conversion failed` | Item not found, already processed, or task creation failed | ### curl ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/537059f9-5f06-44c7-9098-7b72b5cc629e/convert \ -H "Authorization: Bearer <jwt>" ``` --- ## Dismiss Item Dismisses a pending Inbox item. The item is marked as dismissed and no longer appears in the pending list. ``` POST /api/v1/inbox/{id}/dismiss ``` ### Path Parameters | Parameter | Type | Description | |-----------|------|-------------| | `id` | UUID | Inbox item ID | ### Headers | Header | Required | Value | |--------|----------|-------| | `Authorization` | Yes | `Bearer <jwt>` | ### Response `200 OK` ```json { "status": "dismissed" } ``` ### Errors | Code | Error | Cause | |------|-------|-------| | `400` | `invalid item ID` | Path parameter is not a valid UUID | | `400` | `dismiss failed` | Item not found or already processed | ### curl ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/537059f9-5f06-44c7-9098-7b72b5cc629e/dismiss \ -H "Authorization: Bearer <jwt>" ``` --- ## Bulk Action Perform the same action on several Inbox items in a single request. Supports bulk dismiss and bulk convert. ``` POST /api/v1/inbox/bulk ``` ### Headers | Header | Required | Value | |--------|----------|-------| | `Authorization` | Yes | `Bearer <jwt>` | | `Content-Type` | Yes | `application/json` | ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `ids` | array of UUIDs | **Yes** | Item IDs to act on (1–100 items) | | `action` | string | **Yes** | Action to perform: `"convert"` or `"dismiss"` | ### Example Request: Bulk Dismiss ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/bulk \ -H "Authorization: Bearer <jwt>" \ -H "Content-Type: application/json" \ -d '{ "ids": [ "537059f9-5f06-44c7-9098-7b72b5cc629e", "63f75b47-da37-4e35-8511-a9fd0bb3ba29", "8d66ad8f-c012-4837-9821-df54b55c0e2c" ], "action": "dismiss" }' ``` ### Example Request: Bulk Convert ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/bulk \ -H "Authorization: Bearer <jwt>" \ -H "Content-Type: application/json" \ -d '{ "ids": [ "537059f9-5f06-44c7-9098-7b72b5cc629e", "63f75b47-da37-4e35-8511-a9fd0bb3ba29" ], "action": "convert" }' ``` ### Response `200 OK` ```json { "processed": 3, "failed": 0 } ``` | Field | Type | Description | |-------|------|-------------| | `processed` | integer | Number of items successfully processed | | `failed` | integer | Number of items that failed | > [!note] Partial success > For bulk convert, partial failures return the result with both `processed` and `failed` counts. Individual item errors are included in an `errors` object keyed by item ID. ### Errors | Code | Error | Cause | |------|-------|-------| | `400` | `no IDs provided` | Empty IDs array | | `400` | `maximum 100 items per bulk action` | Too many IDs | | `400` | `invalid action: X (must be 'convert' or 'dismiss')` | Unknown action | | `400` | `all conversions failed: ...` | Every item in bulk convert failed | ### Validation Rules | Rule | Limit | |------|-------| | Minimum items | 1 | | Maximum items | 100 | | Valid actions | `"convert"`, `"dismiss"` | --- ## Common Workflows ### Triage Workflow 1. External services send data via [[API-Reference/Webhooks|webhooks]] 2. Items appear in your pending Inbox 3. Review items with `GET /api/v1/inbox` 4. Convert actionable items with `POST /api/v1/inbox/{id}/convert` 5. Dismiss noise with `POST /api/v1/inbox/{id}/dismiss` 6. Use bulk actions for batch processing ### Auto-Convert Workflow 1. Configure the integration with `auto_convert: true` in the template config 2. External services send data via webhooks 3. Items are converted to Zaphiri tasks automatically (skipping the Inbox) 4. Check the [[API-Reference/Integrations#Get Webhook Logs|webhook logs]] to confirm delivery 5. Find created tasks by `task_id` in the webhook response > [!tip] Start manual, then automate > Begin with manual triage to understand what each integration sends. Once you trust the data quality, turn on auto-convert to skip the Inbox entirely. --- **Next:** [[API-Reference/Examples|Examples & Scenarios]] | **Start:** [[API-Reference/API-Reference|API Reference]]