Inbound mail reviews API

This article and the rest of the API documentation in this section are written for a technical audience — integrators and developers connecting external systems to Tickiti. Familiarity with HTTP, REST, JSON and bearer-token authentication is assumed.

When Tickiti opens a ticket from an incoming email but cannot be sure the email belongs on its own, it holds the ticket for review: the sender is not a participant on the ticket the email refers to, the email duplicates a ticket that is already open, or the sender already has an open ticket. A member of staff then keeps the email as a ticket of its own, or merges it into the existing ticket. These endpoints list the reviews waiting and resolve them, with the same result as the review page.

All endpoints are POST, take and return JSON, and use the response envelope described in the API overview.

Endpoints

Method & pathAbilityPurpose
POST /api/v1/tickets/reviewstickets:readList pending reviews
POST /api/v1/tickets/review-resolvetickets:writeKeep the ticket, or merge its email into the existing ticket

Who may do what

A call runs as the token’s owner, with the same rules as the ticket operations:

  1. Listing and keeping need sight of the ticket under review: its assignee (in person or through a team), a participant, or access to its queue.
  2. Merging also needs sight of the existing ticket, and Manage on both tickets’ queues, as tickets/merge does: a merge adds the sender to the existing ticket as a participant, so it changes both.
  3. From an Axial agent task, a merge that would add someone outside your team to the existing ticket is not made: it waits for a person’s approval as a card on the task’s ticket, and the call returns 202 with status: "awaiting_approval" and the card’s approval_id. A task that is not on a ticket puts the card on the ticket under review when the call names it by ticket_number; given only review_id, it is refused with 403. A reply task only reads, so its merge is always refused with 403. A merge that adds nobody new, and keep, go ahead.

Integration identities (the System user, API user accounts, and on a self-hosted installation sysadmins and superusers) work on tickets in every queue.

List pending reviews

POST /api/v1/tickets/reviews

Body, all optional:

  1. reason — non_party_response (the sender is not a participant on the ticket the email refers to), duplicate (the email duplicates an open ticket) or existant (the sender already has an open ticket).
  2. queue — the queue of the ticket under review, by name.
  3. ticket_number — the review of that ticket, or the reviews that point at it as the existing ticket.
  4. limit — 1 to 200, default 50. more in the reply says there are further reviews.

Reviews come newest first. Each gives the review_id, the reason with a reason_description in words, the ticket under review and the existing_ticket it points at (number, subject, queue, status, originator and creation time), and whether the owner may keep it or merge it.

{
  "ok": true,
  "data": {
    "reviews": [
      {
        "review_id": 58,
        "reason": "existant",
        "reason_description": "The sender already has an open ticket. Merge folds this email into it; keep leaves it a ticket of its own.",
        "created_at": "2026-11-13T07:58:21+00:00",
        "ticket": { "number": "640219", "subject": "Re: size exchange", "queue": "Inbox", "status": "open",
                    "originator_email": "[email protected]", "created_at": "2026-11-13T07:58:20+00:00" },
        "existing_ticket": { "number": "528641", "subject": "Kestrel Pro 3 size exchange", "queue": "Support", "status": "on-hold",
                             "originator_email": "[email protected]", "created_at": "2026-11-10T14:12:03+00:00" },
        "existing_ticket_state": "visible",
        "can_keep": true,
        "can_merge": true
      }
    ],
    "more": false
  }
}

The existing ticket is shown only when the owner can see it too. Otherwise existing_ticket is null and existing_ticket_state is hidden, or gone when that ticket has been deleted.

Resolve a review

POST /api/v1/tickets/review-resolve

Body: review_id, or ticket_number for the ticket under review, and decision:

  1. keep — the review is closed and the ticket stays a ticket of its own. The reply gives the review_id, the decision and the ticket_number.
  2. merge — every message on the ticket under review, oldest first and with its attachments, and the ticket’s participants move to the existing ticket, which reopens if it was on hold and tells its assignee that it reopened; the merge is recorded on it, and the ticket under review is deleted. The reply gives surviving_ticket_number and merged_ticket_number.

A review’s merge carries the email that opened the ticket and every message added to it since, so a customer who wrote again before the review was resolved loses nothing. Each one goes onto the existing ticket as the customer’s mail does when it arrives. An inbound email is never merged into a task: when the existing entry is a task, can_merge is false and a merge is refused (422 refused, for example #640219 is a ticket and #528641 is a task: merging works only between two tickets or two tasks. Keep it instead.). A review that has already been resolved gives 404.