Tickets
Create with email
Starts a new conversation with a customer: creates one ticket, as creating a ticket does, and emails its first message to the recipients from the chosen mailbox, with the ticket's subject as it is (no "RE:") and its body and attachments. The first To address becomes the requester; the mailbox must be active and belong to one of the calling User's groups, and later replies on the ticket go out from it too. The ticket's first message is shown as sent by the User (ticket first_message_sent_as_email), no new-ticket auto-reply or new-ticket notifications are sent and no AI suggested reply is written to it; the same rate limits, plan limits and recipient limits as for replies apply. It is refused until Deskhero has reviewed the workspace; contact support to enable it.
POST
/api/{tenant:minlength(2)}/v{version:apiVersion}/tickets/new_email
Request arguments
| Name | Type | Source |
|---|---|---|
| input | DTO_ticket_new_email | Body |
Request body example
Response
Response body example
DTO_ticket_new_email
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| mailbox_id | Int32 | Id of the mailbox the email is sent from. It must be active and belong to one of the calling User's groups; later replies on the ticket go out from it too | |
| email_addresses | DTO_email_address[] | Who the email goes to, each entry directed TO, CC or BCC (any other direction is rejected), at least one TO, capped at 20 recipients and at 3 on the free plan; none of them may be one of the workspace's own addresses. The first TO address becomes the ticket's requester | |
| ticket | DynApiTicketInput | The ticket, as for creating a ticket: its subject is the email's subject (without "RE:") and its rich-text body and attachments are the email's. A requester given here is ignored: it is the first TO address |
DTO_ticket
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| id | Int32 | ReadOnly | The ticket number, assigned by Deskhero on creation and unique within the workspace |
| group | DTO_reference | The group that owns the ticket, which decides which Users can see it, or null when no group is set | |
| assignee | DTO_reference | The User the ticket is assigned to, or null when nobody has been assigned yet | |
| requester | DTO_contact | The contact who asked for help, created automatically from the sender address when the ticket arrives by email | |
| created | DateTime | ReadOnly | When the ticket was created, in UTC |
| created_by | DTO_reference_user | ReadOnly | The User who created the ticket, null when it came from someone who is not a User in the workspace |
| last_updated | DateTime | ReadOnly | When the ticket was last written to, in UTC, which any change moves forward and not only new messages |
| last_updated_by | DTO_reference_user | ReadOnly | The User behind the most recent change, null when the change did not come from a User (inbound email or a background job, for example) |
| last_message | DateTime (nullable) | ReadOnly | When the most recent message was added to the ticket, in UTC, starting out equal to created on a brand new ticket |
| reply_count | Int32 | ReadOnly | Number of replies and notes recorded on the ticket, excluding the message it was created from, AI reply suggestions and static auto-reply acknowledgements |
| ai_reply | Boolean | ReadOnly | True when the ticket has received an AI-generated auto-reply |
| chat_bot_resolved | Boolean (nullable) | ReadOnly | Chat-bot session outcome: true = visitor confirmed the bot answered their question, false = visitor said No. Null when not rated / not a chat ticket. |
| source | String | ReadOnly | How the ticket was created (EMAIL, FORM, CHAT_BOT, ...) |
| reply_history | DTO_ticket_reply_history[] | ReadOnly | One entry per message counted in reply_count, each naming the conversation, its type and who sent it |
| sys_priority | DTO_reference_color | Priority of the ticket, referencing one of the priority values configured for the workspace, and carrying that value's display colours | |
| sys_status | DTO_reference_color | Status of the ticket, referencing one of the statuses configured for the workspace, and carrying that status's display colours | |
| sys_subject | String | Subject line of the ticket, taken from the email subject when the ticket arrives by email | |
| sys_content_rich | DTO_rich_text | Body of the message the ticket was created from, carried as rich text in whichever of the html, tiptap and editorjs representations was stored | |
| suggested_reply_status | ENUM suggested_reply_status | Progress of the AI reply suggestion for the ticket: IN_PROGRESS while it is being generated, DONE when one is available, ERROR_NO_KNOWLEDGE when the knowledge base held nothing relevant, and ERROR_UNKNOWN for any other failure. | |
| sys_attachments | DTO_reference_attachment[] | Files attached to the message the ticket was created from, each referenced by its attachment id |
DTO_email_address
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| String | |||
| name | String | Name | |
| direction | ENUM email_address_direction | Direction |
DTO_reference
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| id | Int32 | The id of the reference | |
| label | Object | ReadOnly | Name/Label from referenced object. |
DTO_contact
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| user_id | Int32 | User id | |
| String | |||
| name | String | Name | |
| profile_pic | String | Profile pic |
DTO_reference_user
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| profile_pic | String | ReadOnly | Profile pic |
| String | ReadOnly | ||
| id | Int32 | Id | |
| label | Object | ReadOnly | Label |
DTO_ticket_reply_history
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| by | DTO_reference_user | By | |
| id | Int32 | Id | |
| type | ENUM ticket_conversation_type | Type | |
| created | DateTime | Created |
DTO_reference_color
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| bg_color | String | ReadOnly | Bg color |
| text_color | String | ReadOnly | Text color |
| id | Int32 | Id | |
| label | Object | ReadOnly | Label |
DTO_rich_text
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| plain_preview | String | ReadOnly | Plain preview |
| html | String | Html | |
| editorjs | DTO_editorjs | Editorjs | |
| tiptap | DTO_tiptap | Tiptap | |
| read_minutes | Int32 | Read minutes |
DTO_editorjs
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| time | Int64 | Time | |
| version | String | Version | |
| blocks | DTO_editorjs_block[] | Blocks |
DTO_editorjs_block
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| id | String | Id | |
| type | String | Type | |
| data | Object | Data |
DTO_tiptap
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| type | String | Type | |
| content | DTO_tiptap_node[] | Content |
DTO_tiptap_node
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| type | String | Type | |
| attrs | DTO_tiptap_attrs | Attrs | |
| content | DTO_tiptap_node[] | Content | |
| text | String | Text | |
| marks | DTO_tiptap_mark[] | Marks |
DTO_tiptap_attrs
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| textAlign | String | Textalign | |
| level | Int32 (nullable) | Level | |
| checked | Boolean (nullable) | Checked | |
| id | Int32 (nullable) | Id | |
| alt | String | Alt | |
| title | String | Title | |
| width | String | Width | |
| wrapperStyle | String | Wrapperstyle | |
| containerStyle | String | Containerstyle | |
| files | DTO_tiptap_file_ref[] | Files | |
| href | String | Href | |
| target | String | Target | |
| colspan | Int32 (nullable) | Colspan | |
| rowspan | Int32 (nullable) | Rowspan | |
| color | String | Color | |
| text | String | Text | |
| name | String | For emoji | |
| native | String | For emoji |
DTO_tiptap_file_ref
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| id | Int32 | Id | |
| label | String | Label |
DTO_tiptap_mark
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| type | String | Type | |
| attrs | DTO_tiptap_attrs | Attrs |
DTO_reference_attachment
| Name | Type | ReadOnly | Description |
|---|---|---|---|
| size_kb | Int32 | ReadOnly | Size kb |
| status | ENUM attachment_status | ReadOnly | Status |
| status_message | String | ReadOnly | Status message |
| download_url | String | ReadOnly | Download url |
| id | Int32 | Id | |
| label | Object | ReadOnly | Label |
ENUM email_address_direction
| Value | Name | Description |
|---|---|---|
| 0 | UNKNOWN | UNKNOWN |
| 1 | FROM | FROM |
| 2 | TO | TO |
| 3 | CC | CC |
| 4 | BCC | BCC |
| 5 | FORWARDED_TO | FORWARDED_TO |
| 6 | RESENT_FROM | RESENT_FROM |
| 7 | REPLY_TO | REPLY_TO |
ENUM ticket_conversation_type
| Value | Name | Description |
|---|---|---|
| 0 | UNKNOWN | UNKNOWN |
| 1 | REPLY_INBOUND | REPLY_INBOUND |
| 2 | NOTE_PRIVATE | NOTE_PRIVATE |
| 3 | NOTE_PUBLIC | NOTE_PUBLIC |
| 4 | FORWARD | FORWARD |
| 5 | REPLY_OUTBOUND | REPLY_OUTBOUND |
| 6 | SUGGESTED_REPLY | SUGGESTED_REPLY |
| 7 | AUTO_REPLY_AI | AUTO_REPLY_AI |
| 8 | AUTO_REPLY_STATIC | AUTO_REPLY_STATIC |
| 9 | CHAT_USER | CHAT_USER |
| 10 | CHAT_BOT | CHAT_BOT |
| 11 | SUMMARY_AI | AI-generated recap of the whole thread, requested by a User from the ticket view. Internal only: never emailed, never fed back into AI context, and not counted as a reply. |
ENUM attachment_status
| Value | Name | Description |
|---|---|---|
| 0 | UNKNOWN | UNKNOWN |
| 1 | UNAVAILABLE | UNAVAILABLE, processing in progress |
| 2 | OK | OK |
| 3 | WARNING | WARNING |
| 4 | ERROR | ERROR |
ENUM suggested_reply_status
| Value | Name | Description |
|---|---|---|
| 0 | UNKNOWN | UNKNOWN |
| 1 | IN_PROGRESS | In progress |
| 2 | DONE | Done |
| 3 | ERROR_NO_KNOWLEDGE | Error no knowledge |
| 4 | ERROR_UNKNOWN | Error unknown |
Generated Nov 3, 2026 05:19