Tickets

Handle data related to ImBox Tickets.

listTickets

Get tickets within a given timespan. If more than limit tickets exist, the next result set can be fetched using the href in ”next”.

Parameters

Name	Type	Description
apiKey*	String	Your API key
userId*	String	Unique id for the user

Query parameters

Name	Type	Description
limit	Integer	Number of tickets to return
updatedAfter	Date string	returns items where updatedDate >= updatedAfter
updatedBefore	Date string	returns items where updatedDate <= updatedBefore
latestUpdatedAfter	Date string	returns items where latestUpdatedDate >= latestUpdatedAfter
latestUpdatedBefore	Date string	returns items where latestUpdatedDate <= latestUpdatedBefore
fromEmail	String	Email address
status	String	”new” | ”reply” | ”pending” | ”solved” | ”closed” | ”on-hold”
fileType	String	Response type. ”csv” | ”json”. Default: ”json”
cursorId	Integer	Cursor for next result set
cursorUpdated	Integer	Cursor for next result set
label	String	Filter tickets by label. Can be repeated: &label=a&label=b returns tickets matching any of the specified labels

updatedDate is an automatic timestamp updated anytime the database row changes. latestUpdatedDate is updated when actions happen to the ticket, like a change in status or an assignment of an agent.

Usage

curl -X GET "https://apiv2.imbox.io/message/listTickets/:apiKey/:userId?updatedAfter=2020-01-01&limit=2"

Response

{
  "result": "success",
  "json": [
    {
      "sid": 1,
      "inboxName": "Support",
      "ticketID": 1,
      "status": "pending",
      "subject": "Re: Booking",
      "fromEmail": "john.doe@example.org",
      "labels": ["label1", "label2"],
      "createdDate": "2020-01-01T00:00:00.000Z",
      "updatedDate": "2020-01-01T00:00:00.000Z",
      "latestUpdated": "2020-01-01T00:00:00.000Z"
    },
    {
      "sid": 1,
      "inboxName": "Info",
      "ticketID": 2,
      "status": "new",
      "subject": "My booking",
      "fromEmail": "john.doe@example.org",
      "labels": [],
      "createdDate": "2020-01-01T00:00:00.000Z",
      "updatedDate": "2020-01-01T00:00:00.000Z",
      "latestUpdated": "2020-01-01T00:00:00.000Z"
    }
  ],
  "length": 2,
  "next": "https://apiv2.imbox.io/message/listTickets/apiKey/userId?updatedAfter=2020-01-01&limit=2&cursorId=2&cursorUpdated=1686819359320"
}

API key scope access

Configure API key access in ImBox Admin dashboard.

Scope	Access
Tickets	Read

grabTicket

Get a ticket.

Parameters

Name	Type	Description
apiKey*	String	Your API key
userId*	String	Unique id for the user
ticketId*	String	Id for ticket

Usage

curl -X GET "https://apiv2.imbox.io/message/grabTicket/:apiKey/:userId/:ticketId"

Response

{
  "result": "success",
  "json": [
    {
      "sid": 1,
      "ticketID": "1",
      "from": "john.doe@example.org",
      "fromName": "John",
      "agentID": 1, // Null if not sent by agent
      "messageType": "external", // External / Internal / Log
      "messagePlain": "Hello", // Plain text content
      "messageHtml": "<p>Hello</p&gt", // Raw HTML content
      "attachments": ["https://example.com/image.png"], // URLs to attachments
      "date": "2020-01-01T00:00:00.000Z" // Sent time
    }
  ],
  "length": 1,
  "meta": {
    "tags": [{ "tag": "tag name" }],
    "labels": [{ "label": "label name" }],
    "notes": "notes content",
    "linkedTickets": [{ "ticketId": 123 }],
    "ticketStatus": "pending",
    "assignedAgents": [
      {
        "id": 7878,
        "agentName": "Agent1 Name",
        "agentEmail": "agent1@company.com"
      },
      {
        "id": 7979,
        "agentName": "Agent2 Name",
        "agentEmail": "agent2@company.com"
      }
    ],
    "customFields": [
      {
        "title": "Order number",
        "value": "12345"
      }
    ]
  }
}

API key scope access

Configure API key access in ImBox Admin dashboard.

Scope	Access
Tickets	Read

insertTicket

Create a ticket.

Note: When creating tickets with the insertTicket API Mail Flow will be bypassed. This means for example any automatic labeling setup in Mail Flow will not apply on these tickets. Please define desired actions directly in the request.

Parameters

Name	Type	Description
apiKey*	String	Your API key
userId*	String	Unique id for the user

Body

Name	Type	Description
fromEmail*	String	Ex. "john.doe@example.org"
fromName	String	Ex. "John"
message*	String	Ticket content
subject*	String	Ticket subject
toEmail*	String	Email connected to your ImBox account. "info@your-company.com"
appendOpenTicket	Boolean	Append to already open ticket from same sender? Default: true
attachments	Array<String>	Adding uploaded files to ticket. Total file size limit of 50 MB. Ex: ["https://yourfile.com", "https://yourfile2.com"]
assignAgents	Array<String>	Email addresses for ImBox agents that will be assigned to the ticket. The agents need access to the mailbox for assign to be possible.
autoReply	Boolean	Send auto reply to "fromEmail" (if auto replies are activated on your ticket mailbox). Default: true
labels	Array<String>	Adding label names on Ticket. Ex. "Support"
messageType	String	"internal" | "external". "internal" means a private note will be created in the ticket. Default: "external".
status	String	"new" | "reply" | "pending" | "solved" | "closed" | "on-hold"
ticketId	String	Append message to a specific ticket (ticket cannot be deleted)

Usage

curl -X POST -H "Content-Type: application/json" -d @ticket.json "https://apiv2.imbox.io/message/insertTicket/<apiKey>/<userId"

ticket.json

{
  "fromEmail": "john.doe@example.com",
  "toEmail": "info@your-company.se",
  "subject": "My subject",
  "message": "My message"
}

Response

{
  "result": "success",
  "json": {
    "ticketID": 1234
  }
}

API key scope access

Configure API key access in ImBox Admin dashboard.

Scope	Access
Tickets	Write

listTicketsEmails

Lists all email addresses for sent and received mails within a timespan. If more than limit emails exist, the next result set can be fetched using the href in ”next”.

Parameters

Name	Type	Description
apiKey*	String	Your API key
userId*	String	Unique id for the user

Query parameters

Name	Type	Description
limit	Integer	Number of emails to return
startTime*	Date string
endTime*	Date string
timezone	String	Time zone. Default: Europe/Stockholm
fileType	String	Response type. ”csv” | ”json”. Default: ”json”
cursorId	Integer	Cursor for next result set
cursorCreated	Integer	Cursor for next result set

Usage

curl -X GET "https://apiv2.imbox.io/message/listTicketsEmails/:apiKey/:userId?startTime=2020-01-01&endTime=2020-01-02&limit=2"

Response

{
  "result": "success",
  "json": [
    {
      "createdDate": "2020-01-01T00:00:00.000Z",
      "inboxName": "Company Support",
      "from": { "address": "agent@example.org", "name": "agent" },
      "ticketID": 1,
      "to": [{ "address": "customer@example.org" }],
      "cc": [],
      "bcc": []
    },
    {
      "createdDate": "2020-01-01T00:00:00.000Z",
      "inboxName": "Company Support",
      "from": { "address": "agent2@example.org", "name": "Agent 2" },
      "ticketID": 2,
      "to": [{ "address": "another-customer@example.org" }],
      "cc": [{ "address": "ccd@example.org" }],
      "bcc": []
    }
  ],
  "next": "https://apiv2.imbox.io/message/listTicketsEmails/apiKey/userId?startTime=2020-01-01&endTime=2020-01-02&limit=2&cursorId=1234&cursorCreated=1577836800000",
  "length": 2
}

API key scope access

Configure API key access in ImBox Admin dashboard.

Scope	Access
Tickets	Read