Introduction

Authentication

GET /teammates HTTP/1.1
Host: api2.frontapp.com
Authorization: Bearer <token>

You should replace “<token>” in the example above by your JSON Web Token.

The API uses JSON Web Token to authenticate its user.

You MUST send the token for each request in the Authorization header. The token MUST be preceeded by Bearer

You can get your JSON web token directly from Front (go to Settings > API & Integrations > API).

Content type

POST /channels/{channel_id}/messages HTTP/1.1
Host: api2.frontapp.com
Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json

{}

The API is designed to communicate with your server using JSON. All responses coming from the API will send data in a valid JSON object. If you need to send data to the API, your request SHOULD set the Content-Type HTTP header to application/json.

Some endpoints also support multipart requests for file upload. For more details about it, please check our multipart request documentation.

Limitations

Rate limiting

By default, the API is limited to 120 requests in 60 seconds. If you need more, just ask us and we will consider raising your quota. Every response will contains three headers related to the rate-limiting:

Example of a response to a request exceeding the rate limit. The client should wait 20s before resending the request.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1454450858
Retry-After: 20

Name	Description
`X-RateLimit-Limit`	Maximum number of request allowed in the time window
`X-RateLimit-Remaining`	Current remaining number of requests in the current time window
`X-RateLimit-Reset`	Next timestamp when the number of remaining requests will be reset

When the rate limit is exceeded, the server will respond with a 429 Too Many Requests HTTP code with the header Retry-After to tell you how many seconds you need to wait before you can retry the request.

Individual inboxes and channels

Since individual inboxes and channels are private, the API does not let you interact with them nor with their content.

Resource aliases

You can refer to all the resources with their IDs. Alternatively, some resources can be accessed via a more human readable alias:

Teammates can be identified with their email.
Channels can be identified with their address.
Contacts can be identified with one of their source and handle.
Conversations can be identified with their reference.

If you want to use an alternative alias, you MUST prefix it with alt: and the name of the value used to identify the resource. Examples:

alt:email:leela@planet-express.com for the teammate with the email address leela@planet-express.com.
alt:address:@FrontApp for the channel with the address @FrontApp.
alt:twitter:@leela for the contact having the twitter handle @leela.
alt:phone:+12345678900 for the contact having the phone number +12345678900.
alt:ref:3b1q41d8@frontapp.com for the conversation with the reference 3b1q41d8@frontapp.com.

Dates

All dates in the Front API are encoded as a number representing Unix time: It is the number of seconds that have elapsed since 00:00:00 UTC, January 1st 1970.

Since Front is based on events that can occur during the same second, all the timestamps include leap seconds with a precision of 3 digits: 1454453901.012.

Search parameters

For some requests to get a large collection of resources, you can send search criteria in the query string via a parameter named q.

Fetch all conversations deleted and assigned:

GET /conversations?q[statuses][]=deleted&q[statuses][]=assigned HTTP/1.1
Host: api2.frontapp.com
Accept: application/json
Authorization: Bearer <token>

Search criteria for conversations

Name	Type	Description
`statuses`	array (optional)	List of the statuses of the conversations you want to list

Fetch all comment and assign events between Jan 25th, 2016 at 2:00 pm and January 25th, 2016 at 5:00 pm:

GET /events?q[types][]=comment&q[types][]=assign&q[after]=1453730400&q[before]=1453741200 HTTP/1.1
Host: api2.frontapp.com
Accept: application/json
Authorization: Bearer <token>

Search criteria for events

Name	Type	Description
`types`	array (optional)	List of the types of events you want to list
`before`	number (optional)	Timestamp of the max date of the events you want to list
`after`	number (optional)	Timestamp of the min date of the events you want to list

Response body structure

A JSON object will be at the root of every responses body. When requesting a resource collections, the collection will be encapsulated in a _results field.

A response will contain at least one of the following top-level members:

_pagination: An object containing pagination information.
_links: An object containing the resource links for self-discoverability.
_errors: An array of error objects.

Pagination

When listing a large number of resources, the API server will return a limited number of results. When this is the case, the JSON response will contain a field named _pagination.

Name	Type	Description
`limit`	number	Max number of results per page
`prev`	string (optional)	URL of the previous page
`next`	string (optional)	URL of the next page

Links

To improve the self-discoverability of our API, every resources contains a _links object:

Name	Type	Description
`self`	string	URL of the resource
`related`	object (optional)	Object listing the URL of related resources

Error

When the response is an error, its body will contain an _error object to describe the error.

An error object looks like this:

Name	Type	Description
`status`	number	HTTP status code applicable to the error
`title`	string	Human-readable summary of the problem
`message`	string	Human-readable explanation of the error
`details`	array	List of string detailing the error

Teammates

Name Type Description

_links object See Response body Structure - Links

_links.self string URL of the teammate

_links.related object

_links.related.inboxes string URL of the teammate’s inboxes

_links.related.conversations string URL of the teammate’s conversation

id string Unique identifier of the teammate

email string Email address of the teammate

username string Username of the teammate (used for “@” mentions)

first_name string First name of the teammate

last_name string Last name of the teammate

is_admin boolean Whether or not the teammate is an admin in your company

is_available boolean Whether or not the teammate is available

Name	Type	Description
_links	object	See Response body Structure - Links
_links.self	string	URL of the teammate
_links.related	object
_links.related.inboxes	string	URL of the teammate’s inboxes
_links.related.conversations	string	URL of the teammate’s conversation
id	string	Unique identifier of the teammate
email	string	Email address of the teammate
username	string	Username of the teammate (used for “@” mentions)
first_name	string	First name of the teammate
last_name	string	Last name of the teammate
is_admin	boolean	Whether or not the teammate is an admin in your company
is_available	boolean	Whether or not the teammate is available

A teammate is a Front user, a member of your company.

A teammate can be available or not (determined by the boolean is_available). When a conversation is assigned to an unavailable teammate, to avoid it to be hidden from the other teammates, it gets unassigned automatically.

You can use the teammate email address as an alias for its ID.
A teammate ID alias follows the pattern alt:email:{email address}.

List team


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/teammates'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/teammates"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
        "related": {
          "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
          "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
        }
      },
      "id": "tea_55c8c149",
      "email": "leela@planet-express.com",
      "username": "leela",
      "first_name": "Leela",
      "last_name": "Turanga",
      "is_admin": true,
      "is_available": true
    }
  ]
}

Lists the teammates in your company.

HTTP Request

GET https://api2.frontapp.com/teammates

Get teammate


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/teammates/${TEAMMATE_ID}'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
    "related": {
      "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
      "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
    }
  },
  "id": "tea_55c8c149",
  "email": "leela@planet-express.com",
  "username": "leela",
  "first_name": "Leela",
  "last_name": "Turanga",
  "is_admin": true,
  "is_available": true
}

Fetches the information of a teammate. See resource aliases to fetch by email.

HTTP Request

GET https://api2.frontapp.com/teammates/{teammate_id}

Parameters

Name	Type	Description
teammate_id	string	Id or email of the requested teammate

Update teammate


curl --include \
     --request PATCH \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
     --data-binary "{
  \"username\": \"bender\",
  \"first_name\": \"Bender\",
  \"last_name\": \"Rodriguez\",
  \"is_admin\": true,
  \"is_available\": false
}" \
'https://api2.frontapp.com/teammates/${TEAMMATE_ID}'

Response 204

Updates the information of a teammate.

HTTP Request

PATCH https://api2.frontapp.com/teammates/{teammate_id}

Parameters

Name	Type	Description
teammate_id	string	Id or email of the requested teammate

Body

Name	Type	Description
username	string (optional)	New username. It must be unique and can only contains lowercase letters, numbers and underscores.
first_name	string (optional)	New first name
last_name	string (optional)	New last name
is_admin	boolean (optional)	New admin status
is_available	boolean (optional)	New availability status

List teammate conversations


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/teammates/${TEAMMATE_ID}/conversations?q=${Q}&page=${PAGE}&limit=${LIMIT}'

Response 200

{
  "_pagination": {
    "limit": 50
  },
  "_links": {
    "self": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/conversations/cnv_55c8c149",
        "related": {
          "events": "https://api2.frontapp.com/conversations/cnv_55c8c149/events",
          "followers": "https://api2.frontapp.com/conversations/cnv_55c8c149/followers",
          "messages": "https://api2.frontapp.com/conversations/cnv_55c8c149/messages",
          "comments": "https://api2.frontapp.com/conversations/cnv_55c8c149/comments",
          "inboxes": "https://api2.frontapp.com/conversations/cnv_55c8c149/inboxes"
        }
      },
      "id": "cnv_55c8c149",
      "subject": "You broke my heart, Hubert.",
      "status": "archived",
      "assignee": {
        "_links": {
          "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
          "related": {
            "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
            "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
          }
        },
        "id": "tea_55c8c149",
        "email": "leela@planet-express.com",
        "username": "leela",
        "first_name": "Leela",
        "last_name": "Turanga",
        "is_admin": true,
        "is_available": true
      },
      "recipient": {
        "_links": {
          "related": {
            "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
          }
        },
        "handle": "calculon@momsbot.com",
        "role": "to"
      },
      "tags": [
        {
          "_links": {
            "self": "https://api2.frontapp.com/tags/tag_55c8c149",
            "related": {
              "conversations": "https://api2.frontapp.com/tags/tag_55c8c149/conversations"
            }
          },
          "id": "tag_55c8c149",
          "name": "Robots"
        }
      ],
      "last_message": {
        "_links": {
          "self": "https://api2.frontapp.com/messages/msg_55c8c149",
          "related": {
            "conversation": "https://api2.frontapp.com/conversations/cnv_55c8c149",
            "message_replied_to": "https://api2.frontapp.com/messages/msg_1ab23cd4"
          }
        },
        "id": "msg_55c8c149",
        "type": "email",
        "is_inbound": true,
        "created_at": 1453770984.123,
        "blurb": "Anything less than immortality is a...",
        "author": {
          "_links": {
            "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
            "related": {
              "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
              "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
            }
          },
          "id": "tea_55c8c149",
          "email": "leela@planet-express.com",
          "username": "leela",
          "first_name": "Leela",
          "last_name": "Turanga",
          "is_admin": true,
          "is_available": true
        },
        "recipients": [
          {
            "_links": {
              "related": {
                "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
              }
            },
            "handle": "calculon@momsbot.com",
            "role": "to"
          }
        ],
        "body": "Anything less than immortality is a complete waste of time.",
        "text": "Anything less than immortality is a complete waste of time.",
        "attachments": [
          {
            "filename": "attachment.jpg",
            "url": "https://api2.frontapp.com/download/fil_55c8c149",
            "content_type": "image/jpeg",
            "size": 10000,
            "metadata": {
              "is_inline": true,
              "cid": "123456789"
            }
          }
        ],
        "metadata": {}
      },
      "created_at": 1453770984.123
    }
  ]
}

Lists the conversations assigned to a teammate in reverse chronological order (newest first).

HTTP Request

GET https://api2.frontapp.com/teammates/{teammate_id}/conversations?q={q}&page={page}&limit={limit}

Parameters

Name	Type	Description
teammate_id	string	Id or email of the teammate
q	object (optional)	Search query. See Search Parameters
page	number (optional)	Number of the page requested
limit	number (optional)	Max number of results per page (default 50, maximum 100)

List teammate inboxes


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/teammates/${TEAMMATE_ID}/inboxes'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/inboxes/inb_55c8c149",
        "related": {
          "teammates": "https://api2.frontapp.com/inboxes/inb_55c8c149/teammates",
          "conversations": "https://api2.frontapp.com/inboxes/inb_55c8c149/conversations",
          "channels": "https://api2.frontapp.com/inboxes/inb_55c8c149/channels"
        }
      },
      "id": "inb_55c8c149",
      "address": "team@planet-express.com",
      "type": "smtp",
      "name": "Team",
      "send_as": "team@planet-express.com"
    }
  ]
}

Lists the inboxes a teammate has access to.

HTTP Request

GET https://api2.frontapp.com/teammates/{teammate_id}/inboxes

Parameters

Name	Type	Description
teammate_id	string	Id or email of the teammate

Inboxes

Name Type Description

_links object See Response body Structure - Links

_links.self string URL of the inbox

_links.related object

_links.related.teammates string URL of the list of teammates that can access the inbox

_links.related.conversations string URL of the list of conversations included in this inbox

_links.related.channels string URL of the list of channels sending messages to this inbox

id string Unique identifier for the inbox

address string DEPRECATED in favor of channel Address receiving the messages

type enum DEPRECATED in favor of channel Type of the inbox

name string Name of the inbox

send_as string (optional) DEPRECATED in favor of channel Address which appears as the sender for messages sent from Front

Name	Type	Description
_links	object	See Response body Structure - Links
_links.self	string	URL of the inbox
_links.related	object
_links.related.teammates	string	URL of the list of teammates that can access the inbox
_links.related.conversations	string	URL of the list of conversations included in this inbox
_links.related.channels	string	URL of the list of channels sending messages to this inbox
id	string	Unique identifier for the inbox
address	string	DEPRECATED in favor of channel Address receiving the messages
type	enum	DEPRECATED in favor of channel Type of the inbox
name	string	Name of the inbox
send_as	string (optional)	DEPRECATED in favor of channel Address which appears as the sender for messages sent from Front

An inbox is a container of messages.

Messages are sent from and received by channels which then post the messages into the configured inbox. An inbox can have multiple channels.

List inboxes


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/inboxes'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/inboxes"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/inboxes/inb_55c8c149",
        "related": {
          "teammates": "https://api2.frontapp.com/inboxes/inb_55c8c149/teammates",
          "conversations": "https://api2.frontapp.com/inboxes/inb_55c8c149/conversations",
          "channels": "https://api2.frontapp.com/inboxes/inb_55c8c149/channels"
        }
      },
      "id": "inb_55c8c149",
      "address": "team@planet-express.com",
      "type": "smtp",
      "name": "Team",
      "send_as": "team@planet-express.com"
    }
  ]
}

Lists all the team inboxes in your company.

HTTP Request

GET https://api2.frontapp.com/inboxes

Create an inbox


curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
     --data-binary "{
  \"name\": \"Delivery support\",
  \"teammate_ids\": []
}" \
'https://api2.frontapp.com/inboxes'

Response 201

{
  "id": "inb_55c8c149",
  "name": "Delivery support"
}

Creates a team inbox with no channel associated to it (see Create a channel).

HTTP Request

POST https://api2.frontapp.com/inboxes

Body

Name	Type	Description
name	string	Name of the inbox
teammate_ids	array (optional)	List of all the teammate ids who will have access to this inbox. If omitted, it will automatically select all the administrators in your company.

Get inbox


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/inboxes/${INBOX_ID}'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/inboxes/inb_55c8c149",
    "related": {
      "teammates": "https://api2.frontapp.com/inboxes/inb_55c8c149/teammates",
      "conversations": "https://api2.frontapp.com/inboxes/inb_55c8c149/conversations",
      "channels": "https://api2.frontapp.com/inboxes/inb_55c8c149/channels"
    }
  },
  "id": "inb_55c8c149",
  "address": "team@planet-express.com",
  "type": "smtp",
  "name": "Team",
  "send_as": "team@planet-express.com"
}

Fetches the information of an inbox.

HTTP Request

GET https://api2.frontapp.com/inboxes/{inbox_id}

Parameters

Name	Type	Description
inbox_id	string	Id of the requested inbox

List inbox channels


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/inboxes/${INBOX_ID}/channels'

Response 200

{
  "_pagination": {
    "limit": 50
  },
  "_links": {
    "self": "https://api2.frontapp.com/inboxes/inb_55c8c149/channels"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/channels/cha_55c8c149",
        "related": {
          "inbox": "https://api2.frontapp.com/channels/cha_55c8c149/inbox"
        }
      },
      "id": "cha_55c8c149",
      "address": "team@planet-express.com",
      "type": "smtp",
      "send_as": "team@planet-express.com",
      "settings": {}
    }
  ]
}

Lists the channels linked to an inbox.

HTTP Request

GET https://api2.frontapp.com/inboxes/{inbox_id}/channels

Parameters

Name	Type	Description
inbox_id	string	Id of the requested inbox

List inbox conversations


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/inboxes/${INBOX_ID}/conversations?q=${Q}&page=${PAGE}&limit=${LIMIT}'

Response 200

{
  "_pagination": {
    "limit": 50
  },
  "_links": {
    "self": "https://api2.frontapp.com/inboxes/inb_55c8c149/conversations"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/conversations/cnv_55c8c149",
        "related": {
          "events": "https://api2.frontapp.com/conversations/cnv_55c8c149/events",
          "followers": "https://api2.frontapp.com/conversations/cnv_55c8c149/followers",
          "messages": "https://api2.frontapp.com/conversations/cnv_55c8c149/messages",
          "comments": "https://api2.frontapp.com/conversations/cnv_55c8c149/comments",
          "inboxes": "https://api2.frontapp.com/conversations/cnv_55c8c149/inboxes"
        }
      },
      "id": "cnv_55c8c149",
      "subject": "You broke my heart, Hubert.",
      "status": "archived",
      "assignee": {
        "_links": {
          "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
          "related": {
            "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
            "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
          }
        },
        "id": "tea_55c8c149",
        "email": "leela@planet-express.com",
        "username": "leela",
        "first_name": "Leela",
        "last_name": "Turanga",
        "is_admin": true,
        "is_available": true
      },
      "recipient": {
        "_links": {
          "related": {
            "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
          }
        },
        "handle": "calculon@momsbot.com",
        "role": "to"
      },
      "tags": [
        {
          "_links": {
            "self": "https://api2.frontapp.com/tags/tag_55c8c149",
            "related": {
              "conversations": "https://api2.frontapp.com/tags/tag_55c8c149/conversations"
            }
          },
          "id": "tag_55c8c149",
          "name": "Robots"
        }
      ],
      "last_message": {
        "_links": {
          "self": "https://api2.frontapp.com/messages/msg_55c8c149",
          "related": {
            "conversation": "https://api2.frontapp.com/conversations/cnv_55c8c149",
            "message_replied_to": "https://api2.frontapp.com/messages/msg_1ab23cd4"
          }
        },
        "id": "msg_55c8c149",
        "type": "email",
        "is_inbound": true,
        "created_at": 1453770984.123,
        "blurb": "Anything less than immortality is a...",
        "author": {
          "_links": {
            "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
            "related": {
              "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
              "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
            }
          },
          "id": "tea_55c8c149",
          "email": "leela@planet-express.com",
          "username": "leela",
          "first_name": "Leela",
          "last_name": "Turanga",
          "is_admin": true,
          "is_available": true
        },
        "recipients": [
          {
            "_links": {
              "related": {
                "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
              }
            },
            "handle": "calculon@momsbot.com",
            "role": "to"
          }
        ],
        "body": "Anything less than immortality is a complete waste of time.",
        "text": "Anything less than immortality is a complete waste of time.",
        "attachments": [
          {
            "filename": "attachment.jpg",
            "url": "https://api2.frontapp.com/download/fil_55c8c149",
            "content_type": "image/jpeg",
            "size": 10000,
            "metadata": {
              "is_inline": true,
              "cid": "123456789"
            }
          }
        ],
        "metadata": {}
      },
      "created_at": 1453770984.123
    }
  ]
}

Lists the conversations which appear in an inbox.

HTTP Request

GET https://api2.frontapp.com/inboxes/{inbox_id}/conversations?q={q}&page={page}&limit={limit}

Parameters

Name	Type	Description
inbox_id	string	Id of the requested inbox
q	object (optional)	Search query. See Search Parameters
page	number (optional)	Number of the page requested
limit	number (optional)	Max number of results per page (default 50, maximum 100)

List inbox teammates


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/inboxes/${INBOX_ID}/teammates'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/inboxes/inb_55c8c149/teammates"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
        "related": {
          "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
          "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
        }
      },
      "id": "tea_55c8c149",
      "email": "leela@planet-express.com",
      "username": "leela",
      "first_name": "Leela",
      "last_name": "Turanga",
      "is_admin": true,
      "is_available": true
    }
  ]
}

Lists the teammates who can access an inbox.

HTTP Request

GET https://api2.frontapp.com/inboxes/{inbox_id}/teammates

Parameters

Name	Type	Description
inbox_id	string	Id of the requested inbox

Channels

Name Type Description

_links object See Response body Structure - Links

_links.self string URL of the channel.

_links.related object

_links.related.inbox string URL of the inbox to which the channel is sending messages.

id string Unique identifier for the channel.

address string Address receiving the messages.

type enum Type of the channel.

send_as string (optional) Address which appears as the sender for messages sent from Front.

settings object

Name	Type	Description
_links	object	See Response body Structure - Links
_links.self	string	URL of the channel.
_links.related	object
_links.related.inbox	string	URL of the inbox to which the channel is sending messages.
id	string	Unique identifier for the channel.
address	string	Address receiving the messages.
type	enum	Type of the channel.
send_as	string (optional)	Address which appears as the sender for messages sent from Front.
settings	object

A channel is a resource which can send and receive messages.

Here is the list of existing channel types:

Type	Description
`smtp`	For emails managed via SMTP.
`imap`	For emails managed via IMAP.
`twilio`	Linked to a Twilio account.
`twitter`	Linked to a Twitter account.
`facebook`	Linked to a Facebook page.
`smooch`	Linked to a Smooch account.
`intercom`	Linked to an Intercom account.
`truly`	Linked to a truly account.
`custom`	For messages sent and received only through the API (cf Custom inboxes).

List channels


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/channels'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/channels"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/channels/cha_55c8c149",
        "related": {
          "inbox": "https://api2.frontapp.com/channels/cha_55c8c149/inbox"
        }
      },
      "id": "cha_55c8c149",
      "address": "team@planet-express.com",
      "type": "smtp",
      "send_as": "team@planet-express.com",
      "settings": {}
    }
  ]
}

Lists all the shared channels available in your company.

You can use the channel address as an alias for its ID.
A channel ID alias follows the pattern alt:address:{address}.

HTTP Request

GET https://api2.frontapp.com/channels

Get a channel


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/channels/${CHANNEL_ID}'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/channels/cha_55c8c149",
    "related": {
      "inbox": "https://api2.frontapp.com/channels/cha_55c8c149/inbox"
    }
  },
  "id": "cha_55c8c149",
  "address": "team@planet-express.com",
  "type": "smtp",
  "send_as": "team@planet-express.com",
  "settings": {}
}

Fetches the information of a channel. See resource aliases to fetch by address.

HTTP Request

GET https://api2.frontapp.com/channels/{channel_id}

Parameters

Name	Type	Description
channel_id	string	Id of the requested channel

Update a channel settings


curl --include \
     --request PATCH \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
     --data-binary "{
  \"settings\": {
    \"webhook_url\": \"http://example.com\"
  }
}" \
'https://api2.frontapp.com/channels/${CHANNEL_ID}'

Response 204

Updates the settings of a channel.

HTTP Request

PATCH https://api2.frontapp.com/channels/{channel_id}

Parameters

Name	Type	Description
channel_id	string	Id of the requested channel

Body

Name	Type	Description
settings	object
settings.webhook_url	string (optional)	`custom` type only. URL to which will be sent the replies of a custom message.

Create a channel


curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
     --data-binary "{
  \"type\": \"custom\",
  \"settings\": {
    \"webhook_url\": \"http://example.com\"
  }
}" \
'https://api2.frontapp.com/inboxes/${INBOX_ID}/channels'

Response 201

{
  "id": "cha_55c8c149",
  "type": "custom",
  "address": "dw0a0b7aeg36cb56",
  "sendAs": "dw0a0b7aeg36cb56",
  "settings": {
    "webhook_url": "http://example.com"
  }
}

Creates a channel linked to the requested inbox.

HTTP Request

POST https://api2.frontapp.com/inboxes/{inbox_id}/channels

Parameters

Name	Type	Description
inbox_id	string	Id of the inbox into which the channel messages will go.

Body

Name	Type	Description
type	enum	Type of the channel.
settings	object
settings.webhook_url	string (optional)	`custom` type only. URL to which will be sent the replies of a custom message.

Get channel inbox


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/channels/${CHANNEL_ID}/inbox'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/inboxes/inb_55c8c149",
    "related": {
      "teammates": "https://api2.frontapp.com/inboxes/inb_55c8c149/teammates",
      "conversations": "https://api2.frontapp.com/inboxes/inb_55c8c149/conversations",
      "channels": "https://api2.frontapp.com/inboxes/inb_55c8c149/channels"
    }
  },
  "id": "inb_55c8c149",
  "address": "team@planet-express.com",
  "type": "smtp",
  "name": "Team",
  "send_as": "team@planet-express.com"
}

Fetches the inbox to which the channel is linked to.

HTTP Request

GET https://api2.frontapp.com/channels/{channel_id}/inbox

Parameters

Name	Type	Description
channel_id	string	Id of the requested channel

Conversations

Name Type Description

_links object See Response body Structure - Links

_links.self string URL of the conversation

_links.related object

_links.related.events string URL of the activities related to the conversation

_links.related.followers string URL of the teammates following the conversation

_links.related.messages string URL of the list of messages in the conversation

_links.related.comments string URL of the comments for the conversation

_links.related.inboxes string URL of the inboxes in which the conversation appears

id string Unique identifier of the conversation

subject string Subject of the conversation

status enum (optional) Status of the conversation

assignee Teammate (optional) Partial representation of the teammate assigned to the conversation

recipient Recipient Main recipient of the conversation

tags array List of the tags for this conversation

last_message Message List of partial representation of the messages inside the conversation

created_at number Timestamp at which the conversation have been created.

Name	Type	Description
_links	object	See Response body Structure - Links
_links.self	string	URL of the conversation
_links.related	object
_links.related.events	string	URL of the activities related to the conversation
_links.related.followers	string	URL of the teammates following the conversation
_links.related.messages	string	URL of the list of messages in the conversation
_links.related.comments	string	URL of the comments for the conversation
_links.related.inboxes	string	URL of the inboxes in which the conversation appears
id	string	Unique identifier of the conversation
subject	string	Subject of the conversation
status	enum (optional)	Status of the conversation
assignee	Teammate (optional)	Partial representation of the teammate assigned to the conversation
recipient	Recipient	Main recipient of the conversation
tags	array	List of the tags for this conversation
last_message	Message	List of partial representation of the messages inside the conversation
created_at	number	Timestamp at which the conversation have been created.

A conversation is a unique thread of messages. It can appear in one or more inboxes (eg: if you receive an email on contact@ where support@ is Cced).

Even if a conversation messages can have multiple recipients, the conversation resource will always have only one. The main recipient of a conversation can change over the time depending on each message received. It will generally be the sender of the last incomming message.

Opening a conversation in Front

To open a conversation in Front you need to open the URL https://app.frontapp.com/open/{conversation_id}.

You can use the conversation reference as an alias for its ID. The reference to use can be found in the response of the endpoints to create messages.
A conversation ID alias follows the pattern alt:ref:{reference}.

List conversations


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/conversations?q=${Q}&page=${PAGE}&limit=${LIMIT}'

Response 200

{
  "_pagination": {
    "limit": 50
  },
  "_links": {
    "self": "https://api2.frontapp.com/conversations"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/conversations/cnv_55c8c149",
        "related": {
          "events": "https://api2.frontapp.com/conversations/cnv_55c8c149/events",
          "followers": "https://api2.frontapp.com/conversations/cnv_55c8c149/followers",
          "messages": "https://api2.frontapp.com/conversations/cnv_55c8c149/messages",
          "comments": "https://api2.frontapp.com/conversations/cnv_55c8c149/comments",
          "inboxes": "https://api2.frontapp.com/conversations/cnv_55c8c149/inboxes"
        }
      },
      "id": "cnv_55c8c149",
      "subject": "You broke my heart, Hubert.",
      "status": "archived",
      "assignee": {
        "_links": {
          "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
          "related": {
            "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
            "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
          }
        },
        "id": "tea_55c8c149",
        "email": "leela@planet-express.com",
        "username": "leela",
        "first_name": "Leela",
        "last_name": "Turanga",
        "is_admin": true,
        "is_available": true
      },
      "recipient": {
        "_links": {
          "related": {
            "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
          }
        },
        "handle": "calculon@momsbot.com",
        "role": "to"
      },
      "tags": [
        {
          "_links": {
            "self": "https://api2.frontapp.com/tags/tag_55c8c149",
            "related": {
              "conversations": "https://api2.frontapp.com/tags/tag_55c8c149/conversations"
            }
          },
          "id": "tag_55c8c149",
          "name": "Robots"
        }
      ],
      "last_message": {
        "_links": {
          "self": "https://api2.frontapp.com/messages/msg_55c8c149",
          "related": {
            "conversation": "https://api2.frontapp.com/conversations/cnv_55c8c149",
            "message_replied_to": "https://api2.frontapp.com/messages/msg_1ab23cd4"
          }
        },
        "id": "msg_55c8c149",
        "type": "email",
        "is_inbound": true,
        "created_at": 1453770984.123,
        "blurb": "Anything less than immortality is a...",
        "author": {
          "_links": {
            "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
            "related": {
              "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
              "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
            }
          },
          "id": "tea_55c8c149",
          "email": "leela@planet-express.com",
          "username": "leela",
          "first_name": "Leela",
          "last_name": "Turanga",
          "is_admin": true,
          "is_available": true
        },
        "recipients": [
          {
            "_links": {
              "related": {
                "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
              }
            },
            "handle": "calculon@momsbot.com",
            "role": "to"
          }
        ],
        "body": "Anything less than immortality is a complete waste of time.",
        "text": "Anything less than immortality is a complete waste of time.",
        "attachments": [
          {
            "filename": "attachment.jpg",
            "url": "https://api2.frontapp.com/download/fil_55c8c149",
            "content_type": "image/jpeg",
            "size": 10000,
            "metadata": {
              "is_inline": true,
              "cid": "123456789"
            }
          }
        ],
        "metadata": {}
      },
      "created_at": 1453770984.123
    }
  ]
}

Lists all the conversations in your company in reverse chronological order (latest updated first).

HTTP Request

GET https://api2.frontapp.com/conversations?q={q}&page={page}&limit={limit}

Parameters

Name	Type	Description
q	object (optional)	Search query. See Search Parameters
page	number (optional)	Number of the page requested
limit	number (optional)	Max number of results per page (default 50, maximum 100)

Get conversation


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/conversations/${CONVERSATION_ID}'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/conversations/cnv_55c8c149",
    "related": {
      "events": "https://api2.frontapp.com/conversations/cnv_55c8c149/events",
      "followers": "https://api2.frontapp.com/conversations/cnv_55c8c149/followers",
      "messages": "https://api2.frontapp.com/conversations/cnv_55c8c149/messages",
      "comments": "https://api2.frontapp.com/conversations/cnv_55c8c149/comments",
      "inboxes": "https://api2.frontapp.com/conversations/cnv_55c8c149/inboxes"
    }
  },
  "id": "cnv_55c8c149",
  "subject": "You broke my heart, Hubert.",
  "status": "archived",
  "assignee": {
    "_links": {
      "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
      "related": {
        "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
        "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
      }
    },
    "id": "tea_55c8c149",
    "email": "leela@planet-express.com",
    "username": "leela",
    "first_name": "Leela",
    "last_name": "Turanga",
    "is_admin": true,
    "is_available": true
  },
  "recipient": {
    "_links": {
      "related": {
        "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
      }
    },
    "handle": "calculon@momsbot.com",
    "role": "to"
  },
  "tags": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/tags/tag_55c8c149",
        "related": {
          "conversations": "https://api2.frontapp.com/tags/tag_55c8c149/conversations"
        }
      },
      "id": "tag_55c8c149",
      "name": "Robots"
    }
  ],
  "last_message": {
    "_links": {
      "self": "https://api2.frontapp.com/messages/msg_55c8c149",
      "related": {
        "conversation": "https://api2.frontapp.com/conversations/cnv_55c8c149",
        "message_replied_to": "https://api2.frontapp.com/messages/msg_1ab23cd4"
      }
    },
    "id": "msg_55c8c149",
    "type": "email",
    "is_inbound": true,
    "created_at": 1453770984.123,
    "blurb": "Anything less than immortality is a...",
    "author": {
      "_links": {
        "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
        "related": {
          "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
          "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
        }
      },
      "id": "tea_55c8c149",
      "email": "leela@planet-express.com",
      "username": "leela",
      "first_name": "Leela",
      "last_name": "Turanga",
      "is_admin": true,
      "is_available": true
    },
    "recipients": [
      {
        "_links": {
          "related": {
            "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
          }
        },
        "handle": "calculon@momsbot.com",
        "role": "to"
      }
    ],
    "body": "Anything less than immortality is a complete waste of time.",
    "text": "Anything less than immortality is a complete waste of time.",
    "attachments": [
      {
        "filename": "attachment.jpg",
        "url": "https://api2.frontapp.com/download/fil_55c8c149",
        "content_type": "image/jpeg",
        "size": 10000,
        "metadata": {
          "is_inline": true,
          "cid": "123456789"
        }
      }
    ],
    "metadata": {}
  },
  "created_at": 1453770984.123
}

Fetches the information of a conversation.

HTTP Request

GET https://api2.frontapp.com/conversations/{conversation_id}

Parameters

Name	Type	Description
conversation_id	string	Id of the requested conversation

Update conversation


curl --include \
     --request PATCH \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
     --data-binary "{
  \"assignee_id\": \"alt:email:fry@planet-express.com\",
  \"status\": \"archived\",
  \"tags\": [
    \"time travel\"
  ]
}" \
'https://api2.frontapp.com/conversations/${CONVERSATION_ID}'

Response 204

Updates a conversation. You can:

Assign or unassign a conversation by sending an assignee_id
Update the tags of a conversation by sending an array tags containing the names of the all the tag of a conversation (unknown tags will be automatically created)
Archive a conversation by sending archived in status
Delete a conversation by sending deleted in status
Mark a conversation as spam by sending spam in status
Unarchive or restore a conversation by sending open in status

HTTP Request

PATCH https://api2.frontapp.com/conversations/{conversation_id}

Parameters

Name	Type	Description
conversation_id	string	Id of the requested conversation

Body

Name	Type	Description
assignee_id	string (optional)	ID of the teammate to assign the conversation to. Set it to null to unassign.
inbox_id: `inb_128yew`	string (optional)	ID of the inbox to move the conversation to.
status	enum (optional)	New status of the conversation
tags	array (optional)	List of all the tag names replacing the old conversation tags

List conversation inboxes


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/conversations/${CONVERSATION_ID}/inboxes'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/conversations/cnv_55c8c149/inboxes"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/inboxes/inb_55c8c149",
        "related": {
          "teammates": "https://api2.frontapp.com/inboxes/inb_55c8c149/teammates",
          "conversations": "https://api2.frontapp.com/inboxes/inb_55c8c149/conversations",
          "channels": "https://api2.frontapp.com/inboxes/inb_55c8c149/channels"
        }
      },
      "id": "inb_55c8c149",
      "address": "team@planet-express.com",
      "type": "smtp",
      "name": "Team",
      "send_as": "team@planet-express.com"
    }
  ]
}

Lists the inboxes in which a conversation appears.

HTTP Request

GET https://api2.frontapp.com/conversations/{conversation_id}/inboxes

Parameters

Name	Type	Description
conversation_id	string	Id of the requested conversation

List conversation followers


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/conversations/${CONVERSATION_ID}/followers'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/conversations/cnv_55c8c149/followers"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
        "related": {
          "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
          "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
        }
      },
      "id": "tea_55c8c149",
      "email": "leela@planet-express.com",
      "username": "leela",
      "first_name": "Leela",
      "last_name": "Turanga",
      "is_admin": true,
      "is_available": true
    }
  ]
}

Lists the teammates following a conversation.

HTTP Request

GET https://api2.frontapp.com/conversations/{conversation_id}/followers

Parameters

Name	Type	Description
conversation_id	string	Id of the requested conversation

List conversation events


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/conversations/${CONVERSATION_ID}/events?page=${PAGE}&limit=${LIMIT}'

Response 200

{
  "_pagination": {
    "limit": 50
  },
  "_links": {
    "self": "https://api2.frontapp.com/conversations/cnv_55c8c149/events"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/events/evt_55c8c149"
      },
      "id": "evt_55c8c149",
      "type": "assign",
      "emitted_at": 1453770984.123,
      "source": {
        "_meta": {
          "type": "rule"
        },
        "data": {
          "_links": {
            "self": "https://api2.frontapp.com/rules/rul_55c8c149"
          },
          "id": "rul_55c8c149",
          "name": "Important deliveries",
          "actions": [
            "Assign to Leela Turanga"
          ]
        }
      },
      "target": {
        "_meta": {
          "type": "teammate"
        },
        "data": {
          "_links": {
            "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
            "related": {
              "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
              "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
            }
          },
          "id": "tea_55c8c149",
          "email": "leela@planet-express.com",
          "username": "leela",
          "first_name": "Leela",
          "last_name": "Turanga",
          "is_admin": true,
          "is_available": true
        }
      },
      "conversation": {
        "_links": {
          "self": "https://api2.frontapp.com/conversations/cnv_55c8c149",
          "related": {
            "events": "https://api2.frontapp.com/conversations/cnv_55c8c149/events",
            "followers": "https://api2.frontapp.com/conversations/cnv_55c8c149/followers",
            "messages": "https://api2.frontapp.com/conversations/cnv_55c8c149/messages",
            "comments": "https://api2.frontapp.com/conversations/cnv_55c8c149/comments",
            "inboxes": "https://api2.frontapp.com/conversations/cnv_55c8c149/inboxes"
          }
        },
        "id": "cnv_55c8c149",
        "subject": "You broke my heart, Hubert.",
        "status": "archived",
        "assignee": {
          "_links": {
            "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
            "related": {
              "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
              "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
            }
          },
          "id": "tea_55c8c149",
          "email": "leela@planet-express.com",
          "username": "leela",
          "first_name": "Leela",
          "last_name": "Turanga",
          "is_admin": true,
          "is_available": true
        },
        "recipient": {
          "_links": {
            "related": {
              "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
            }
          },
          "handle": "calculon@momsbot.com",
          "role": "to"
        },
        "tags": [
          {
            "_links": {
              "self": "https://api2.frontapp.com/tags/tag_55c8c149",
              "related": {
                "conversations": "https://api2.frontapp.com/tags/tag_55c8c149/conversations"
              }
            },
            "id": "tag_55c8c149",
            "name": "Robots"
          }
        ],
        "last_message": {
          "_links": {
            "self": "https://api2.frontapp.com/messages/msg_55c8c149",
            "related": {
              "conversation": "https://api2.frontapp.com/conversations/cnv_55c8c149",
              "message_replied_to": "https://api2.frontapp.com/messages/msg_1ab23cd4"
            }
          },
          "id": "msg_55c8c149",
          "type": "email",
          "is_inbound": true,
          "created_at": 1453770984.123,
          "blurb": "Anything less than immortality is a...",
          "author": {
            "_links": {
              "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
              "related": {
                "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
                "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
              }
            },
            "id": "tea_55c8c149",
            "email": "leela@planet-express.com",
            "username": "leela",
            "first_name": "Leela",
            "last_name": "Turanga",
            "is_admin": true,
            "is_available": true
          },
          "recipients": [
            {
              "_links": {
                "related": {
                  "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
                }
              },
              "handle": "calculon@momsbot.com",
              "role": "to"
            }
          ],
          "body": "Anything less than immortality is a complete waste of time.",
          "text": "Anything less than immortality is a complete waste of time.",
          "attachments": [
            {
              "filename": "attachment.jpg",
              "url": "https://api2.frontapp.com/download/fil_55c8c149",
              "content_type": "image/jpeg",
              "size": 10000,
              "metadata": {
                "is_inline": true,
                "cid": "123456789"
              }
            }
          ],
          "metadata": {}
        },
        "created_at": 1453770984.123
      }
    }
  ]
}

List of all the events that occured for a conversation in reverse chronological order (newest first).

HTTP Request

GET https://api2.frontapp.com/conversations/{conversation_id}/events?page={page}&limit={limit}

Parameters

Name	Type	Description
page	number (optional)	Number of the page requested
limit	number (optional)	Max number of results per page (default 50, maximum 100)
conversation_id	string	Id of the requested conversation

List conversation messages


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/conversations/${CONVERSATION_ID}/messages?page=${PAGE}&limit=${LIMIT}'

Response 200

{
  "_pagination": {
    "limit": 50
  },
  "_links": {
    "self": "https://api2.frontapp.com/conversations/cnv_55c8c149/messages"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/messages/msg_55c8c149",
        "related": {
          "conversation": "https://api2.frontapp.com/conversations/cnv_55c8c149",
          "message_replied_to": "https://api2.frontapp.com/messages/msg_1ab23cd4"
        }
      },
      "id": "msg_55c8c149",
      "type": "email",
      "is_inbound": true,
      "created_at": 1453770984.123,
      "blurb": "Anything less than immortality is a...",
      "author": {
        "_links": {
          "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
          "related": {
            "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
            "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
          }
        },
        "id": "tea_55c8c149",
        "email": "leela@planet-express.com",
        "username": "leela",
        "first_name": "Leela",
        "last_name": "Turanga",
        "is_admin": true,
        "is_available": true
      },
      "recipients": [
        {
          "_links": {
            "related": {
              "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
            }
          },
          "handle": "calculon@momsbot.com",
          "role": "to"
        }
      ],
      "body": "Anything less than immortality is a complete waste of time.",
      "text": "Anything less than immortality is a complete waste of time.",
      "attachments": [
        {
          "filename": "attachment.jpg",
          "url": "https://api2.frontapp.com/download/fil_55c8c149",
          "content_type": "image/jpeg",
          "size": 10000,
          "metadata": {
            "is_inline": true,
            "cid": "123456789"
          }
        }
      ],
      "metadata": {}
    }
  ]
}

Lists all the messages sent or received in a conversation in reverse chronological order (newest first).

HTTP Request

GET https://api2.frontapp.com/conversations/{conversation_id}/messages?page={page}&limit={limit}

Parameters

Name	Type	Description
conversation_id	string	Id of the requested conversation
page	number (optional)	Number of the page requested
limit	number (optional)	Max number of results per page (default 50, maximum 100)

Comments

Name Type Description

_links object See Response body Structure - Links

_links.self string URL of the comment

_links.related object

_links.related.conversation string URL of the conversation from which the comment belongs

_links.related.mentions string URL of the teammates mentionned in a comment

id string Unique identifier of the comment

author Teammate Teammate who wrote the comment

body string Content of the comment

posted_at number Date at which the comment have been posted

Name	Type	Description
_links	object	See Response body Structure - Links
_links.self	string	URL of the comment
_links.related	object
_links.related.conversation	string	URL of the conversation from which the comment belongs
_links.related.mentions	string	URL of the teammates mentionned in a comment
id	string	Unique identifier of the comment
author	Teammate	Teammate who wrote the comment
body	string	Content of the comment
posted_at	number	Date at which the comment have been posted

A comment is a private message written by a teammate visible only to the other teammates. It is never sent and cannot be shared outside of Front.

Create comment


curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
     --data-binary "{
  \"author_id\": \"alt:email:leela@planet-express.com\",
  \"body\": \"@bender, I thought you were supposed to be cooking for this party.\"
}" \
'https://api2.frontapp.com/conversations/${CONVERSATION_ID}/comments'

Response 201

{
  "_links": {
    "self": "https://api2.frontapp.com/comments/inb_55c8c149",
    "related": {
      "conversation": "https://api2.frontapp.com/conversations/cnv_55c8c149",
      "mentions": "https://api2.frontapp.com/comments/com_55c8c149/mentions"
    }
  },
  "id": "com_55c8c149",
  "author": {
    "_links": {
      "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
      "related": {
        "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
        "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
      }
    },
    "id": "tea_55c8c149",
    "email": "leela@planet-express.com",
    "username": "leela",
    "first_name": "Leela",
    "last_name": "Turanga",
    "is_admin": true,
    "is_available": true
  },
  "body": "@bender, I thought you were supposed to be cooking for this party.",
  "posted_at": 1453770984.123
}

Adds a comment to a conversation.

HTTP Request

POST https://api2.frontapp.com/conversations/{conversation_id}/comments

Parameters

Name	Type	Description
conversation_id	string	Id of the requested conversation

Body

Name	Type	Description
author_id	string	ID of the teammate creating the comment
body	string	Content of the comment

List conversation comments


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/conversations/${CONVERSATION_ID}/comments'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/conversations/cnv_55c8c149/comments"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/comments/inb_55c8c149",
        "related": {
          "conversation": "https://api2.frontapp.com/conversations/cnv_55c8c149",
          "mentions": "https://api2.frontapp.com/comments/com_55c8c149/mentions"
        }
      },
      "id": "com_55c8c149",
      "author": {
        "_links": {
          "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
          "related": {
            "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
            "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
          }
        },
        "id": "tea_55c8c149",
        "email": "leela@planet-express.com",
        "username": "leela",
        "first_name": "Leela",
        "last_name": "Turanga",
        "is_admin": true,
        "is_available": true
      },
      "body": "@bender, I thought you were supposed to be cooking for this party.",
      "posted_at": 1453770984.123
    }
  ]
}

Lists of all the comments written in a conversation in reverse chronological order (newest first).

HTTP Request

GET https://api2.frontapp.com/conversations/{conversation_id}/comments

Parameters

Name	Type	Description
conversation_id	string	Id of the requested conversation

Get comment


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/comments/${COMMENT_ID}'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/comments/inb_55c8c149",
    "related": {
      "conversation": "https://api2.frontapp.com/conversations/cnv_55c8c149",
      "mentions": "https://api2.frontapp.com/comments/com_55c8c149/mentions"
    }
  },
  "id": "com_55c8c149",
  "author": {
    "_links": {
      "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
      "related": {
        "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
        "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
      }
    },
    "id": "tea_55c8c149",
    "email": "leela@planet-express.com",
    "username": "leela",
    "first_name": "Leela",
    "last_name": "Turanga",
    "is_admin": true,
    "is_available": true
  },
  "body": "@bender, I thought you were supposed to be cooking for this party.",
  "posted_at": 1453770984.123
}

Fetches the information of a comment.

HTTP Request

GET https://api2.frontapp.com/comments/{comment_id}

Parameters

Name	Type	Description
comment_id	string	Id of the comment

List comment mentions


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/comments/${COMMENT_ID}/mentions'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/comments/com_55c8c149/mentions"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
        "related": {
          "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
          "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
        }
      },
      "id": "tea_55c8c149",
      "email": "leela@planet-express.com",
      "username": "leela",
      "first_name": "Leela",
      "last_name": "Turanga",
      "is_admin": true,
      "is_available": true
    }
  ]
}

Lists the teammates mentionned in a comment.

HTTP Request

GET https://api2.frontapp.com/comments/{comment_id}/mentions

Parameters

Name	Type	Description
comment_id	string	Id of the comment

Messages

Name Type Description

_links object See Response body Structure - Links

_links.self string URL of the message

_links.related object

_links.related.conversation string URL of the parent conversation

links.related.messagereplied_to string (optional) URL of the message which have been replied to

id string Unique identifier of the message

type enum Type of the message

is_inbound boolean Whether or not the message has been received or sent

created_at number Date at which the message as been sent or received

blurb string Preview of the message body

author Teammate (optional) In case of a message sent from Front by a teammate, it will include the teammate who sent it

recipients array List of the message recipients

body string Body of the message

text string (optional) Text version of the body for email messages

attachments array List of files attached to the message

metadata object (optional) Optional metadata about the message

metadata.intercom_url string (optional) For intercom messages only. URL of the Intercom conversation the message is comming from.

metadata.duration number (optional) For truly-call messages only. Length of the call in seconds.

metadata.have_been_answered boolean (optional) For truly-call messages only. Whether or not the call have been answered.

metadata.twitter_url string (optional) For tweet messages only. URL of the tweet.

metadata.is_retweet boolean (optional) For tweet messages only. Whether or not the tweet is a retweet.

metadata.have_been_retweeted boolean (optional) For tweet messages only. Whether or not the tweet have been retweeted.

metadata.have_been_favorited boolean (optional) For tweet messages only. Whether or not the tweet have been favorited.

metadata.thread_ref string (optional) For custom messages only. Custom reference which is used to thread messages.

metadata.headers object (optional) For custom messages only. Custom object holding internal information.

Name	Type	Description
_links	object	See Response body Structure - Links
_links.self	string	URL of the message
_links.related	object
_links.related.conversation	string	URL of the parent conversation
links.related.messagereplied_to	string (optional)	URL of the message which have been replied to
id	string	Unique identifier of the message
type	enum	Type of the message
is_inbound	boolean	Whether or not the message has been received or sent
created_at	number	Date at which the message as been sent or received
blurb	string	Preview of the message body
author	Teammate (optional)	In case of a message sent from Front by a teammate, it will include the teammate who sent it
recipients	array	List of the message recipients
body	string	Body of the message
text	string (optional)	Text version of the body for email messages
attachments	array	List of files attached to the message
metadata	object (optional)	Optional metadata about the message
metadata.intercom_url	string (optional)	For `intercom` messages only. URL of the Intercom conversation the message is comming from.
metadata.duration	number (optional)	For `truly-call` messages only. Length of the call in seconds.
metadata.have_been_answered	boolean (optional)	For `truly-call` messages only. Whether or not the call have been answered.
metadata.twitter_url	string (optional)	For `tweet` messages only. URL of the tweet.
metadata.is_retweet	boolean (optional)	For `tweet` messages only. Whether or not the tweet is a retweet.
metadata.have_been_retweeted	boolean (optional)	For `tweet` messages only. Whether or not the tweet have been retweeted.
metadata.have_been_favorited	boolean (optional)	For `tweet` messages only. Whether or not the tweet have been favorited.
metadata.thread_ref	string (optional)	For `custom` messages only. Custom reference which is used to thread messages.
metadata.headers	object (optional)	For `custom` messages only. Custom object holding internal information.

A message is a resource which can be either received or sent via an inbox. Messages are grouped by conversations.

A message can be either inbound (received) or outbound (sent). You can know if a message has been received or sent thanks to the boolean is_inbound.

Each message has a type depending on the channel it has been sent with:

Type name	Description
`email`	Email message
`tweet`	Message from Twitter
`sms`	SMS message
`smooch`	Message from Smooch
`facebook`	Message from Facebook
`intercom`	Message from Intercom
`call`	Phone call
`custom`	Custom message

Opening a message in Front

To open a message in Front you need to open the URL https://app.frontapp.com/open/{message_id}.

Creating messages in Front is done asynchronously: the endpoint will only validate that the message can be processed.
Because of that, the response body does not include a conversation or message ID but includes a conversation_reference that can be used as an alias for the conversation ID. We guarantee that the reference will refer to a conversation but we don’t guarantee that the conversation already exists when you receive its reference. So the API might respond with a 404 error code if trying to use the reference before the conversation exists.

Get message


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/messages/${MESSAGE_ID}'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/messages/msg_55c8c149",
    "related": {
      "conversation": "https://api2.frontapp.com/conversations/cnv_55c8c149",
      "message_replied_to": "https://api2.frontapp.com/messages/msg_1ab23cd4"
    }
  },
  "id": "msg_55c8c149",
  "type": "email",
  "is_inbound": true,
  "created_at": 1453770984.123,
  "blurb": "Anything less than immortality is a...",
  "author": {
    "_links": {
      "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
      "related": {
        "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
        "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
      }
    },
    "id": "tea_55c8c149",
    "email": "leela@planet-express.com",
    "username": "leela",
    "first_name": "Leela",
    "last_name": "Turanga",
    "is_admin": true,
    "is_available": true
  },
  "recipients": [
    {
      "_links": {
        "related": {
          "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
        }
      },
      "handle": "calculon@momsbot.com",
      "role": "to"
    }
  ],
  "body": "Anything less than immortality is a complete waste of time.",
  "text": "Anything less than immortality is a complete waste of time.",
  "attachments": [
    {
      "filename": "attachment.jpg",
      "url": "https://api2.frontapp.com/download/fil_55c8c149",
      "content_type": "image/jpeg",
      "size": 10000,
      "metadata": {
        "is_inline": true,
        "cid": "123456789"
      }
    }
  ],
  "metadata": {}
}

Fetches the information of a message.

You can request the source of a message by setting the Accept header to "text/plain".
Fetching the source of a message is available for email messages only.

HTTP Request

GET https://api2.frontapp.com/messages/{message_id}

Parameters

Name	Type	Description
message_id	string	Id of the requested message

Send new message


curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
     --data-binary "{
  \"author_id\": \"alt:email:leela@planet-exress.com\",
  \"subject\": \"Good news everyone!\",
  \"body\": \"Why is Zoidberg the only one still alone?\",
  \"text\": \"Why is Zoidberg the only one still alone?\",
  \"attachments\": [],
  \"options\": {
    \"tags\": [],
    \"archive\": true
  },
  \"to\": [
    \"calculon@momsbot.com\"
  ],
  \"cc\": [],
  \"bcc\": []
}" \
'https://api2.frontapp.com/channels/${CHANNEL_ID}/messages'

Response 202

{
  "conversation_reference": "3b1q41d8@frontapp.com"
}

Sends a new message from a channel. It will create a new conversation.

If you want to send a new message with attached files, please check how to send multipart request.

HTTP Request

POST https://api2.frontapp.com/channels/{channel_id}/messages

Parameters

Name	Type	Description
channel_id	string	Id or address of the channel from which to send the message

Body

Name	Type	Description
author_id	string (optional)	ID of the teammate on behalf of whom the answer is sent
subject	string (optional)	Subject of the message for email message
body	string	Body of the message
text	string (optional)	Text version of the body for messages with non-text body
attachments	array (optional)	Binary data of the attached files. Available only for multipart request.
options	object (optional)	Sending options
options.tags	array (optional)	List of tag names to add to the conversation (unknown tags will automatically be created)
options.archive	boolean (optional)	Archive the conversation right when sending the reply (Default: `true`)
to	array	List of the recipient handles who will receive this message
cc	array (optional)	List of the recipient handles who will receive a copy of this message
bcc	array (optional)	List of the recipient handles who will receive a blind copy of this message

Send reply


curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
     --data-binary "{
  \"author_id\": \"alt:email:leela@planet-exress.com\",
  \"subject\": \"Good news everyone!\",
  \"body\": \"Why is Zoidberg the only one still alone?\",
  \"text\": \"Why is Zoidberg the only one still alone?\",
  \"attachments\": [],
  \"options\": {
    \"tags\": [],
    \"archive\": true
  },
  \"channel_id\": \"cha_55c8c149\",
  \"to\": [],
  \"cc\": [],
  \"bcc\": []
}" \
'https://api2.frontapp.com/conversations/${CONVERSATION_ID}/messages'

Response 202

Replies to a conversation by sending a message and appending it to the conversation.

If you want to send a reply with attached files, please check how to send multipart request.

HTTP Request

POST https://api2.frontapp.com/conversations/{conversation_id}/messages

Parameters

Name	Type	Description
conversation_id	string	Id of the conversation

Body

Name	Type	Description
author_id	string (optional)	ID of the teammate on behalf of whom the answer is sent
subject	string (optional)	Subject of the message for email message
body	string	Body of the message
text	string (optional)	Text version of the body for messages with non-text body
attachments	array (optional)	Binary data of the attached files. Available only for multipart request.
options	object (optional)	Sending options
options.tags	array (optional)	List of tag names to add to the conversation (unknown tags will automatically be created)
options.archive	boolean (optional)	Archive the conversation right when sending the reply (Default: `true`)
channel_id	string (optional)	Channel through which to send the message. Defaults to the original conversation channel. For imported messages or messages received on multiple channels, you MUST specify a channel ID.
to	array (optional)	List of the recipient handles who will receive this message. By default it will use the recipients of the last received message.
cc	array (optional)	List of the recipient handles who will receive a copy of this message. By default it will use the cc'ed recipients of the last received message.
bcc	array (optional)	List of the recipient handles who will receive a blind copy of this message

Receive custom message


curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
     --data-binary "{
  \"sender\": {
    \"name\": \"hermes\",
    \"handle\": \"hermes_123\"
  },
  \"subject\": \"Question\",
  \"body\": \"Didn't we used to be a delivery company?\",
  \"attachments\": [],
  \"metadata\": {}
}" \
'https://api2.frontapp.com/channels/${CHANNEL_ID}/incoming_messages'

Response 202

{
  "conversation_reference": "3b1q41d8@frontapp.com"
}

Receives a custom message in Front. This endpoint is available for custom channels ONLY.

If you want to receive a custom message with attached files, please check how to send multipart request.

HTTP Request

POST https://api2.frontapp.com/channels/{channel_id}/incoming_messages

Parameters

Name	Type	Description
channel_id	string	Id of the requested custom channel

Body

Name	Type	Description
sender	object	Data of the sender
sender.contact_id	string (optional)	ID of the contact in Front corresponding to the sender
sender.name	string (optional)	Name of the sender
sender.handle	string	Handle of the sender. It can be any string used to uniquely identify the sender
subject	string (optional)	Subject of the message
body	string	Body of the message
body_format	enum (optional)	Format of the message body. (Default: `'markdown'`)
attachments	array (optional)	Binary data of the attached files. Available only for multipart request.
metadata	object (optional)
metadata.thread_ref	string (optional)	Custom reference which will be used to thread messages. If you ommit this field, we’ll thread by sender instead
metadata.headers	object (optional)	Custom object where any internal information can be stored

Import message


curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
     --data-binary "{
  \"sender\": {
    \"handle\": \"calculon@momsbot.com\"
  },
  \"to\": [],
  \"cc\": [],
  \"bcc\": [],
  \"body\": \"\",
  \"external_id\": \"\",
  \"created_at\": 1453770984.123,
  \"tags\": [],
  \"attachments\": [],
  \"metadata\": {
    \"is_inbound\": true,
    \"is_archived\": true,
    \"should_skip_rules\": true
  }
}" \
'https://api2.frontapp.com/inboxes/${INBOX_ID}/imported_messages'

Response 202

{
  "conversation_reference": "3b1q41d8@frontapp.com"
}

Appends a new message into an inbox.

If you want to import a message with attached files, please check how to send multipart request.

HTTP Request

POST https://api2.frontapp.com/inboxes/{inbox_id}/imported_messages

Parameters

Name	Type	Description
inbox_id	string	Id of the inbox into which the message should be append.

Body

Name	Type	Description
sender	object
sender.handle	string	Handle used to reach the contact. Can be an email address, a twitter, handle, a phone number, …
sender.name	string (optional)	Name of the contact.
sender.author_id	string (optional)	ID of the teammate who is the author of the message. Ignored if the message is inbound.
to	array	List of recipient handles who received the message.
cc	array (optional)	List of recipient handles who received a copy of the message.
bcc	array (optional)	List of the recipeient handles who received a blind copy of the message.
subject	string (optional)	Subject of the message.
body	string	Body of the message.
body_format	enum (optional)	Format of the message body. Ignored if the message type is not `email`. (Default: `'markdown'`)
external_id	string	External identifier of the message. Front won’t import two messages with the same external ID.
created_at	number	Date at which the message as been sent or received.
type	enum (optional)	Type of the message to import. (Default: `'email'`)
assignee_id	string (optional)	ID of the teammate who will be assigned to the conversation.
tags	array (optional)	List of tag names to add to the conversation (unknown tags will automatically be created).
attachments	array (optional)	Binary data of the attached files. Available only for multipart request.
metadata	object
metadata.thread_ref	string (optional)	Custom reference which will be used to thread messages. If you ommit this field, we’ll thread by sender instead.
metadata.is_inbound	boolean	Whether or not the message is received (inbound) or sent (outbound) by you.
metadata.is_archived	boolean (optional)	Whether or not the message should be directly archived once imported. (Default: `true`)
metadata.should_skip_rules	boolean (optional)	Whether or not the rules should apply to this message. (Default: `true`)

Contacts

Name Type Description

_links object See Response body Structure - Links

_links.self string URL of the contact

_links.related object

_links.related.notes string URL to list the notes associated to the contact

_links.related.conversations string URL to list the URL associated to the contact

id string Unique identifier of the contact

name string Contact name

description string Contact description

avatar_url string URL of the contact’s avatar

is_spammer boolean Whether or not the contact is a spammer

links array A set of URL associated to the contact

handles array List of the handles and sources with which the contact is reachable.

groups array List of the groups the contact belongs to.

A contact is a person/entity with whom you have communicated.

A contact has several handles to send messages to it. A handle has a source to identify which inbox can send message to this contact:

Source	Description	Example of handle
`email`	An email address	`calculon@pmomsbot.com`
`phone`	A phone number	`+123445678900`
`twitter`	A twitter handle	`@calculon`
`facebook`	A Facebook user ID
`intercom`	An Intercom user ID
`smooch`	A Smooch user ID
`custom`	Custom handle provided in the API endpoint

Each pair handle/source is unique. If you want to move an existing handle from one contact to an other, you need to delete it from the first one and add it to the other one.

You can use a contact source/handle pair as an alias for its ID.
A contact ID alias follows the pattern alt:{source}:{handle}.

List contacts


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/contacts?page=${PAGE}&limit=${LIMIT}'

Response 200

{
  "_pagination": {
    "limit": 50
  },
  "_links": {
    "self": "https://api2.frontapp.com/contacts"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/contacts/ctc_55c8c149",
        "related": {
          "notes": "https://api2.frontapp.com/contacts/ctc_55c8c149/notes",
          "conversations": "https://api2.frontapp.com/contacts/ctc_55c8c149/conversations"
        }
      },
      "id": "ctc_55c8c149",
      "name": "Calculon",
      "description": "#vip #robot #RIP",
      "avatar_url": "http://example.com/calculon.jpg",
      "is_spammer": true,
      "links": [
        "http://example.com"
      ],
      "handles": [
        {
          "handle": "@calculon",
          "source": "twitter"
        }
      ],
      "groups": [
        {
          "_links": {
            "self": "https://api2.frontapp.com/contacts/grp_55c8c149",
            "related": {
              "contacts": "https://api2.frontapp.com/contact_groups/grp_55c8c149/contacts"
            }
          },
          "id": "grp_55c8c149",
          "name": "Customers"
        }
      ]
    }
  ]
}

List all the contacts in your company in alphabetical order.

HTTP Request

GET https://api2.frontapp.com/contacts?page={page}&limit={limit}

Parameters

Name	Type	Description
page	number (optional)	Number of the page requested
limit	number (optional)	Max number of results per page (default 50, maximum 100)

Get contact


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/contacts/${CONTACT_ID}'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/contacts/ctc_55c8c149",
    "related": {
      "notes": "https://api2.frontapp.com/contacts/ctc_55c8c149/notes",
      "conversations": "https://api2.frontapp.com/contacts/ctc_55c8c149/conversations"
    }
  },
  "id": "ctc_55c8c149",
  "name": "Calculon",
  "description": "#vip #robot #RIP",
  "avatar_url": "http://example.com/calculon.jpg",
  "is_spammer": true,
  "links": [
    "http://example.com"
  ],
  "handles": [
    {
      "handle": "@calculon",
      "source": "twitter"
    }
  ],
  "groups": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/contacts/grp_55c8c149",
        "related": {
          "contacts": "https://api2.frontapp.com/contact_groups/grp_55c8c149/contacts"
        }
      },
      "id": "grp_55c8c149",
      "name": "Customers"
    }
  ]
}

Fetches the information of a contact. See resource aliases to fetch by handle.

HTTP Request

GET https://api2.frontapp.com/contacts/{contact_id}

Parameters

Name	Type	Description
contact_id	string	Id or alias of the requested contact

Update contact


curl --include \
     --request PATCH \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
     --data-binary "{
  \"name\": \"Calculon\",
  \"description\": \"#vip #robot #RIP\",
  \"is_spammer\": true,
  \"links\": [
    \"http://example.com\"
  ],
  \"group_names\": [
    \"Customers\"
  ]
}" \
'https://api2.frontapp.com/contacts/${CONTACT_ID}'

Response 204

Updates a contact information.

If you want to update a contact’s avatar, please check how to send multipart request.

HTTP Request

PATCH https://api2.frontapp.com/contacts/{contact_id}

Parameters

Name	Type	Description
contact_id	string	Id or alias of the requested contact

Body

Name	Type	Description
name	string (optional)	Contact name
description	string (optional)	Contact description
avatar	string (optional)	Binary data of the image to use as the contact avatar. Available only for multipart request.
is_spammer	boolean (optional)	Whether or not the contact is marked as a spammer
links	array (optional)	List of all the links of the contact
group_names	array (optional)	List of all the group names the contact belongs to. It will automatically create missing groups.

Create contact


curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
     --data-binary "{
  \"name\": \"Calculon\",
  \"description\": \"#vip #robot #RIP\",
  \"is_spammer\": true,
  \"links\": [
    \"http://example.com\"
  ],
  \"group_names\": [
    \"Customers\"
  ],
  \"handles\": [
    {
      \"handle\": \"@calculon\",
      \"source\": \"twitter\"
    }
  ]
}" \
'https://api2.frontapp.com/contacts'

Response 201

{
  "_links": {
    "self": "https://api2.frontapp.com/contacts/ctc_55c8c149",
    "related": {
      "notes": "https://api2.frontapp.com/contacts/ctc_55c8c149/notes",
      "conversations": "https://api2.frontapp.com/contacts/ctc_55c8c149/conversations"
    }
  },
  "id": "ctc_55c8c149",
  "name": "Calculon",
  "description": "#vip #robot #RIP",
  "avatar_url": "http://example.com/calculon.jpg",
  "is_spammer": true,
  "links": [
    "http://example.com"
  ],
  "handles": [
    {
      "handle": "@calculon",
      "source": "twitter"
    }
  ],
  "groups": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/contacts/grp_55c8c149",
        "related": {
          "contacts": "https://api2.frontapp.com/contact_groups/grp_55c8c149/contacts"
        }
      },
      "id": "grp_55c8c149",
      "name": "Customers"
    }
  ]
}

Creates a new contact.

If you want to create a contact with an avatar, please check how to send multipart request.

HTTP Request

POST https://api2.frontapp.com/contacts

Body

Name	Type	Description
name	string (optional)	Contact name
description	string (optional)	Contact description
avatar	string (optional)	Binary data of the image to use as the contact avatar. Available only for multipart request.
is_spammer	boolean (optional)	Whether or not the contact is marked as a spammer
links	array (optional)	List of all the links of the contact
group_names	array (optional)	List of all the group names the contact belongs to. It will automatically create missing groups.
handles	array	List of the contact handles

Delete contact


curl --include \
     --request DELETE \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/contacts/${CONTACT_ID}'

Response 204

Deletes a contact.

HTTP Request

DELETE https://api2.frontapp.com/contacts/{contact_id}

Parameters

Name	Type	Description
contact_id	string	Id or alias of the requested contact

List contact conversations


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/contacts/${CONTACT_ID}/conversations?q=${Q}&page=${PAGE}&limit=${LIMIT}'

Response 200

{
  "_pagination": {
    "limit": 50
  },
  "_links": {
    "self": "https://api2.frontapp.com/contacts/ctc_55c8c149/conversations"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/conversations/cnv_55c8c149",
        "related": {
          "events": "https://api2.frontapp.com/conversations/cnv_55c8c149/events",
          "followers": "https://api2.frontapp.com/conversations/cnv_55c8c149/followers",
          "messages": "https://api2.frontapp.com/conversations/cnv_55c8c149/messages",
          "comments": "https://api2.frontapp.com/conversations/cnv_55c8c149/comments",
          "inboxes": "https://api2.frontapp.com/conversations/cnv_55c8c149/inboxes"
        }
      },
      "id": "cnv_55c8c149",
      "subject": "You broke my heart, Hubert.",
      "status": "archived",
      "assignee": {
        "_links": {
          "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
          "related": {
            "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
            "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
          }
        },
        "id": "tea_55c8c149",
        "email": "leela@planet-express.com",
        "username": "leela",
        "first_name": "Leela",
        "last_name": "Turanga",
        "is_admin": true,
        "is_available": true
      },
      "recipient": {
        "_links": {
          "related": {
            "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
          }
        },
        "handle": "calculon@momsbot.com",
        "role": "to"
      },
      "tags": [
        {
          "_links": {
            "self": "https://api2.frontapp.com/tags/tag_55c8c149",
            "related": {
              "conversations": "https://api2.frontapp.com/tags/tag_55c8c149/conversations"
            }
          },
          "id": "tag_55c8c149",
          "name": "Robots"
        }
      ],
      "last_message": {
        "_links": {
          "self": "https://api2.frontapp.com/messages/msg_55c8c149",
          "related": {
            "conversation": "https://api2.frontapp.com/conversations/cnv_55c8c149",
            "message_replied_to": "https://api2.frontapp.com/messages/msg_1ab23cd4"
          }
        },
        "id": "msg_55c8c149",
        "type": "email",
        "is_inbound": true,
        "created_at": 1453770984.123,
        "blurb": "Anything less than immortality is a...",
        "author": {
          "_links": {
            "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
            "related": {
              "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
              "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
            }
          },
          "id": "tea_55c8c149",
          "email": "leela@planet-express.com",
          "username": "leela",
          "first_name": "Leela",
          "last_name": "Turanga",
          "is_admin": true,
          "is_available": true
        },
        "recipients": [
          {
            "_links": {
              "related": {
                "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
              }
            },
            "handle": "calculon@momsbot.com",
            "role": "to"
          }
        ],
        "body": "Anything less than immortality is a complete waste of time.",
        "text": "Anything less than immortality is a complete waste of time.",
        "attachments": [
          {
            "filename": "attachment.jpg",
            "url": "https://api2.frontapp.com/download/fil_55c8c149",
            "content_type": "image/jpeg",
            "size": 10000,
            "metadata": {
              "is_inline": true,
              "cid": "123456789"
            }
          }
        ],
        "metadata": {}
      },
      "created_at": 1453770984.123
    }
  ]
}

Lists all the conversations with a contact in reverse chronological order (newest first).

HTTP Request

GET https://api2.frontapp.com/contacts/{contact_id}/conversations?q={q}&page={page}&limit={limit}

Parameters

Name	Type	Description
q	object (optional)	Search query. See Search Parameters
page	number (optional)	Number of the page requested
limit	number (optional)	Max number of results per page (default 50, maximum 100)
contact_id	string	Id or alias of the requested contact

Contact groups

Name Type Description

_links object See Response body Structure - Links

_links.self string URL of the group

_links.related object

_links.related.contacts string URL to list of contacts in the group

id string Unique identifier of the group

name string Name of the group

List groups


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/contact_groups'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/contact_groups"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/contacts/grp_55c8c149",
        "related": {
          "contacts": "https://api2.frontapp.com/contact_groups/grp_55c8c149/contacts"
        }
      },
      "id": "grp_55c8c149",
      "name": "Customers"
    }
  ]
}

Lists the groups available in your company

HTTP Request

GET https://api2.frontapp.com/contact_groups

Create group


curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
     --data-binary "{
  \"name\": \"Customers\"
}" \
'https://api2.frontapp.com/contact_groups'

Response 201

{
  "_links": {
    "self": "https://api2.frontapp.com/contacts/grp_55c8c149",
    "related": {
      "contacts": "https://api2.frontapp.com/contact_groups/grp_55c8c149/contacts"
    }
  },
  "id": "grp_55c8c149",
  "name": "Customers"
}

Creates a new contact group

HTTP Request

POST https://api2.frontapp.com/contact_groups

Body

Name	Type	Description
name	string	Name of the group

Delete group


curl --include \
     --request DELETE \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/contact_groups/${GROUP_ID}'

Response 204

Deletes a contact group. Will not delete the contacts in this group.

HTTP Request

DELETE https://api2.frontapp.com/contact_groups/{group_id}

Parameters

Name	Type	Description
group_id	string	Id of the requested group

List contacts in a group


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/contact_groups/${GROUP_ID}/contacts?page=${PAGE}&limit=${LIMIT}'

Response 200

{
  "_pagination": {
    "limit": 50
  },
  "_links": {
    "self": "https://api2.frontapp.com/contact_groups/grp_55c8c149/contacts"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/contacts/ctc_55c8c149",
        "related": {
          "notes": "https://api2.frontapp.com/contacts/ctc_55c8c149/notes",
          "conversations": "https://api2.frontapp.com/contacts/ctc_55c8c149/conversations"
        }
      },
      "id": "ctc_55c8c149",
      "name": "Calculon",
      "description": "#vip #robot #RIP",
      "avatar_url": "http://example.com/calculon.jpg",
      "is_spammer": true,
      "links": [
        "http://example.com"
      ],
      "handles": [
        {
          "handle": "@calculon",
          "source": "twitter"
        }
      ],
      "groups": [
        {
          "_links": {
            "self": "https://api2.frontapp.com/contacts/grp_55c8c149",
            "related": {
              "contacts": "https://api2.frontapp.com/contact_groups/grp_55c8c149/contacts"
            }
          },
          "id": "grp_55c8c149",
          "name": "Customers"
        }
      ]
    }
  ]
}

Lists all the contacts belonging to the requested group.

HTTP Request

GET https://api2.frontapp.com/contact_groups/{group_id}/contacts?page={page}&limit={limit}

Parameters

Name	Type	Description
group_id	string	Id of the requested group
page	number (optional)	Number of the page requested
limit	number (optional)	Max number of results per page (default 50, maximum 100)

Add contacts in a group


curl --include \
     --request POST \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/contact_groups/${GROUP_ID}/contacts'

Response 204

Adds a list of contacts in the requested group

HTTP Request

POST https://api2.frontapp.com/contact_groups/{group_id}/contacts

Parameters

Name	Type	Description
group_id	string	Id of the requested group

Body

Name	Type	Description
contact_ids	array	List of ids or aliases of the contacts to add in the requested group

Contact handles

Name Type Description

handle string Handle used to reach the contact. Can be an email address, a twitter, handle, a phone number, …

source enum Can be ‘twitter’, 'email’ or 'phone’.

Add contact handle


curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
     --data-binary "{
  \"handle\": \"@calculon\",
  \"source\": \"twitter\"
}" \
'https://api2.frontapp.com/contacts/${CONTACT_ID}/handles'

Response 204

Adds a new handle/source to a contact.

HTTP Request

POST https://api2.frontapp.com/contacts/{contact_id}/handles

Parameters

Name	Type	Description
contact_id	string	Id or alias of the requested contact

Body

Name	Type	Description
handle	string	Handle used to reach the contact. Can be an email address, a twitter, handle, a phone number, …
source	enum	Can be 'twitter’, 'email’ or 'phone’.

Delete contact handle


curl --include \
     --request DELETE \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
     --data-binary "{
  \"handle\": \"@calculon\",
  \"source\": \"twitter\"
}" \
'https://api2.frontapp.com/contacts/${CONTACT_ID}/handles'

Response 204

Removes a handle/source from a contact.

HTTP Request

DELETE https://api2.frontapp.com/contacts/{contact_id}/handles

Parameters

Name	Type	Description
contact_id	string	Id or alias of the requested contact

Body

Name	Type	Description
handle	string	Handle used to reach the contact. Can be an email address, a twitter, handle, a phone number, …
source	enum	Can be 'twitter’, 'email’ or 'phone’.

Contact notes

Name Type Description

author Teammate Teammate who wrote the note

body string Content of the note

created_at number Date at which the note have been created

List contact notes


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/contacts/${CONTACT_ID}/notes'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/contacts/ctc_55c8c149/notes"
  },
  "_results": [
    {
      "author": {
        "_links": {
          "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
          "related": {
            "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
            "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
          }
        },
        "id": "tea_55c8c149",
        "email": "leela@planet-express.com",
        "username": "leela",
        "first_name": "Leela",
        "last_name": "Turanga",
        "is_admin": true,
        "is_available": true
      },
      "body": "Calculon is a celebrated actor",
      "created_at": 1453770984.123
    }
  ]
}

Lists the notes added to a contact.

HTTP Request

GET https://api2.frontapp.com/contacts/{contact_id}/notes

Parameters

Name	Type	Description
contact_id	string	Id or alias of the requested contact

Add a note


curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
     --data-binary "{
  \"author_id\": \"alt:email:leela@planet-express.com\",
  \"body\": \"Calculon is a celebrated actor\"
}" \
'https://api2.frontapp.com/contacts/${CONTACT_ID}/notes'

Response 201

{
  "author": {
    "_links": {
      "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
      "related": {
        "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
        "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
      }
    },
    "id": "tea_55c8c149",
    "email": "leela@planet-express.com",
    "username": "leela",
    "first_name": "Leela",
    "last_name": "Turanga",
    "is_admin": true,
    "is_available": true
  },
  "body": "Calculon is a celebrated actor",
  "created_at": 1453770984.123
}

Adds a new note to a contact.

HTTP Request

POST https://api2.frontapp.com/contacts/{contact_id}/notes

Parameters

Name	Type	Description
contact_id	string	Id or alias of the requested contact

Body

Name	Type	Description
author_id	string	ID of the teammate creating the note
body	string	Content of the note

Topics

Name Type Description

_links object See Response body Structure - Links

_links.self string URL of the topic

_links.related object

_links.related.conversations string URL of the list of conversations associated to this topictag

id string Unique identifier of the topic

name string Name of the topic

url string URL of the topic

A topic is a specific kind of tag that links to an external platform.

List topic conversations


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/topics/${TOPIC_ID}/conversations?q=${Q}&page=${PAGE}&limit=${LIMIT}'

Response 200

{
  "_pagination": {
    "limit": 50
  },
  "_links": {
    "self": "https://api2.frontapp.com/topics/top_55c8c149/conversations"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/conversations/cnv_55c8c149",
        "related": {
          "events": "https://api2.frontapp.com/conversations/cnv_55c8c149/events",
          "followers": "https://api2.frontapp.com/conversations/cnv_55c8c149/followers",
          "messages": "https://api2.frontapp.com/conversations/cnv_55c8c149/messages",
          "comments": "https://api2.frontapp.com/conversations/cnv_55c8c149/comments",
          "inboxes": "https://api2.frontapp.com/conversations/cnv_55c8c149/inboxes"
        }
      },
      "id": "cnv_55c8c149",
      "subject": "You broke my heart, Hubert.",
      "status": "archived",
      "assignee": {
        "_links": {
          "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
          "related": {
            "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
            "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
          }
        },
        "id": "tea_55c8c149",
        "email": "leela@planet-express.com",
        "username": "leela",
        "first_name": "Leela",
        "last_name": "Turanga",
        "is_admin": true,
        "is_available": true
      },
      "recipient": {
        "_links": {
          "related": {
            "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
          }
        },
        "handle": "calculon@momsbot.com",
        "role": "to"
      },
      "tags": [
        {
          "_links": {
            "self": "https://api2.frontapp.com/tags/tag_55c8c149",
            "related": {
              "conversations": "https://api2.frontapp.com/tags/tag_55c8c149/conversations"
            }
          },
          "id": "tag_55c8c149",
          "name": "Robots"
        }
      ],
      "last_message": {
        "_links": {
          "self": "https://api2.frontapp.com/messages/msg_55c8c149",
          "related": {
            "conversation": "https://api2.frontapp.com/conversations/cnv_55c8c149",
            "message_replied_to": "https://api2.frontapp.com/messages/msg_1ab23cd4"
          }
        },
        "id": "msg_55c8c149",
        "type": "email",
        "is_inbound": true,
        "created_at": 1453770984.123,
        "blurb": "Anything less than immortality is a...",
        "author": {
          "_links": {
            "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
            "related": {
              "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
              "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
            }
          },
          "id": "tea_55c8c149",
          "email": "leela@planet-express.com",
          "username": "leela",
          "first_name": "Leela",
          "last_name": "Turanga",
          "is_admin": true,
          "is_available": true
        },
        "recipients": [
          {
            "_links": {
              "related": {
                "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
              }
            },
            "handle": "calculon@momsbot.com",
            "role": "to"
          }
        ],
        "body": "Anything less than immortality is a complete waste of time.",
        "text": "Anything less than immortality is a complete waste of time.",
        "attachments": [
          {
            "filename": "attachment.jpg",
            "url": "https://api2.frontapp.com/download/fil_55c8c149",
            "content_type": "image/jpeg",
            "size": 10000,
            "metadata": {
              "is_inline": true,
              "cid": "123456789"
            }
          }
        ],
        "metadata": {}
      },
      "created_at": 1453770984.123
    }
  ]
}

Lists all the conversations linked to a specific topic.

HTTP Request

GET https://api2.frontapp.com/topics/{topic_id}/conversations?q={q}&page={page}&limit={limit}

Parameters

Name	Type	Description
topic_id	string	ID of the requested topic
q	object (optional)	Search query. See Search Parameters
page	number (optional)	Number of the page requested
limit	number (optional)	Max number of results per page (default 50, maximum 100)

Rules

Name Type Description

_links object See Response body Structure - Links

_links.self string URL of the rule

id string Unique identifier of the rule

name string Name of the rule

actions array List of the rule’s actions description

A rule is a set of conditions which will trigger automatic actions when they are met.

Since the set of conditions and actions associated to a rule can be quite complicated, the API exposes a human readable version of those.

List rules


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/rules'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/rules"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/rules/rul_55c8c149"
      },
      "id": "rul_55c8c149",
      "name": "Important deliveries",
      "actions": [
        "Assign to Leela Turanga"
      ]
    }
  ]
}

Lists all the shared rules in your company. Individual rules are currently not accessible with the API.

HTTP Request

GET https://api2.frontapp.com/rules

Get rule


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/rules/${RULE_ID}'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/rules/rul_55c8c149"
  },
  "id": "rul_55c8c149",
  "name": "Important deliveries",
  "actions": [
    "Assign to Leela Turanga"
  ]
}

Fetches the definition of a rule.

HTTP Request

GET https://api2.frontapp.com/rules/{rule_id}

Parameters

Name	Type	Description
rule_id	string	ID of the requested rule

Events

Name Type Description

_links object See Response body Structure - Links

_links.self string URL of the event

id string Unique identifier of the event

type enum Type of event

emitted_at number Date at which the event has been emitted

source object The event’s source

source._meta object Metadata about the resource

source._meta.type enum

source.data enum (optional) The resource which triggered the event

target object (optional) Partial representation (type & id) of the event’s target

target._meta object Metadata about the resource

target._meta.type enum

target.data enum (optional) The resource which received the event

conversation Conversation The conversation on which the event happened

An event is created everytime something interesting is happenning in Front. You’ll find in the table bellow the description of all the types of event that exist:

Type	Description	Source types	Target types
`assign`	When a conversation is assigned to a teammate	`teammate` or `rule`	`teammate`
`unassign`	When a conversation is unassigned	`teammate` or `rule`	-
`archive`	When a conversation is archived	`teammate` or `rule`	-
`reopen`	When a conversation is unarchived	`teammate` or `rule`	-
`trash`	When a conversation is deleted	`teammate` or `rule`	-
`restore`	When a conversation is removed from trash	`teammate` or `rule`	-
`comment`	When a teammate comments on a conversation	`teammate`	`comment`
`mention`	When a teammate mention another teammate	`teammate`	`comment`
`inbound`	When an incoming message is received	`inboxes`	`message`
`outbound`	When an outbound message is sent	`inboxes`	`message`
`move`	When a conversation is moved	`teammate` or `rule`	`inboxes`
`forward`	When a message is forwarded	`teammate` or `rule`	`message`
`tag`	When a conversation is tagged	`teammate` or `rule`	`tag`
`untag`	When a conversation is untagged	`teammate` or `rule`	`tag`
`sending_error`	When an inbox cannot send a message	`recipient`	`message`
`reminder`	When a conversation is reopen by a reminder	-	-
`out_reply`	When a reply is sent	`inboxes`	`message`
`conversations_merged`	When two or more conversations are merged	`teammate`	`deleted_conversation_ids`

Event preview

Example: Event preview of a rule assigning a conversation to a teammate:

{
    "_links"      : { "self": "https://api2.frontapp.com/events/evt_55c8c149" },
    "id"          : "evt_55c8c149",
    "type"        : "assign",
    "emitted_at"  : 1453770984.123,
    "source"      : {
        "_meta" : { "type": "rule" },
        "_links": { "self": "https://api2.frontapp.com/rules/rul_55c8c149" },
        "id"    : "rul_55c8c149"
    },
    "target"      : {
        "_meta" : { "type": "teammate" },
        "_links": { "self": "https://api2.frontapp.com/teammates/tea_55c8c149" },
        "id"    : "tea_55c8c149"
    },
    "conversation": {
        "_links": {
            "self"   : "https://api2.frontapp.com/conversations/cnv_55c8c149",
            "related": {
                "events"   : "https://api2.frontapp.com/conversations/cnv_55c8c149/events",
                "followers": "https://api2.frontapp.com/conversations/cnv_55c8c149/followers",
                "messages" : "https://api2.frontapp.com/conversations/cnv_55c8c149/messages",
                "comments" : "https://api2.frontapp.com/conversations/cnv_55c8c149/comments",
                "inboxes"  : "https://api2.frontapp.com/conversations/cnv_55c8c149/inboxes"
            }
        },
        "id"    : "cnv_55c8c149"
    }
}

When receiving an event from Front (either via a webhook or via a custom inbox callback), you will receive the preview of the event. As the callback URL you provided is public, you should not blindly trust any incoming requests. This is why we’re sending only a preview of the event.

An event preview has the exact same structure as the full event except that its source, target and conversation only contain an ID, a link to the resource itself and a type. You can then either request the detailed event or each resources separately by following their respective _links.

List events


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/events?q=${Q}&page=${PAGE}&limit=${LIMIT}'

Response 200

{
  "_pagination": {
    "limit": 50
  },
  "_links": {
    "self": "https://api2.frontapp.com/events"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/events/evt_55c8c149"
      },
      "id": "evt_55c8c149",
      "type": "assign",
      "emitted_at": 1453770984.123,
      "source": {
        "_meta": {
          "type": "rule"
        },
        "data": {
          "_links": {
            "self": "https://api2.frontapp.com/rules/rul_55c8c149"
          },
          "id": "rul_55c8c149",
          "name": "Important deliveries",
          "actions": [
            "Assign to Leela Turanga"
          ]
        }
      },
      "target": {
        "_meta": {
          "type": "teammate"
        },
        "data": {
          "_links": {
            "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
            "related": {
              "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
              "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
            }
          },
          "id": "tea_55c8c149",
          "email": "leela@planet-express.com",
          "username": "leela",
          "first_name": "Leela",
          "last_name": "Turanga",
          "is_admin": true,
          "is_available": true
        }
      },
      "conversation": {
        "_links": {
          "self": "https://api2.frontapp.com/conversations/cnv_55c8c149",
          "related": {
            "events": "https://api2.frontapp.com/conversations/cnv_55c8c149/events",
            "followers": "https://api2.frontapp.com/conversations/cnv_55c8c149/followers",
            "messages": "https://api2.frontapp.com/conversations/cnv_55c8c149/messages",
            "comments": "https://api2.frontapp.com/conversations/cnv_55c8c149/comments",
            "inboxes": "https://api2.frontapp.com/conversations/cnv_55c8c149/inboxes"
          }
        },
        "id": "cnv_55c8c149",
        "subject": "You broke my heart, Hubert.",
        "status": "archived",
        "assignee": {
          "_links": {
            "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
            "related": {
              "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
              "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
            }
          },
          "id": "tea_55c8c149",
          "email": "leela@planet-express.com",
          "username": "leela",
          "first_name": "Leela",
          "last_name": "Turanga",
          "is_admin": true,
          "is_available": true
        },
        "recipient": {
          "_links": {
            "related": {
              "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
            }
          },
          "handle": "calculon@momsbot.com",
          "role": "to"
        },
        "tags": [
          {
            "_links": {
              "self": "https://api2.frontapp.com/tags/tag_55c8c149",
              "related": {
                "conversations": "https://api2.frontapp.com/tags/tag_55c8c149/conversations"
              }
            },
            "id": "tag_55c8c149",
            "name": "Robots"
          }
        ],
        "last_message": {
          "_links": {
            "self": "https://api2.frontapp.com/messages/msg_55c8c149",
            "related": {
              "conversation": "https://api2.frontapp.com/conversations/cnv_55c8c149",
              "message_replied_to": "https://api2.frontapp.com/messages/msg_1ab23cd4"
            }
          },
          "id": "msg_55c8c149",
          "type": "email",
          "is_inbound": true,
          "created_at": 1453770984.123,
          "blurb": "Anything less than immortality is a...",
          "author": {
            "_links": {
              "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
              "related": {
                "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
                "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
              }
            },
            "id": "tea_55c8c149",
            "email": "leela@planet-express.com",
            "username": "leela",
            "first_name": "Leela",
            "last_name": "Turanga",
            "is_admin": true,
            "is_available": true
          },
          "recipients": [
            {
              "_links": {
                "related": {
                  "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
                }
              },
              "handle": "calculon@momsbot.com",
              "role": "to"
            }
          ],
          "body": "Anything less than immortality is a complete waste of time.",
          "text": "Anything less than immortality is a complete waste of time.",
          "attachments": [
            {
              "filename": "attachment.jpg",
              "url": "https://api2.frontapp.com/download/fil_55c8c149",
              "content_type": "image/jpeg",
              "size": 10000,
              "metadata": {
                "is_inline": true,
                "cid": "123456789"
              }
            }
          ],
          "metadata": {}
        },
        "created_at": 1453770984.123
      }
    }
  ]
}

Lists all the detailed events which occured in the inboxes of your company ordered in reverse chronological order (newest first).

HTTP Request

GET https://api2.frontapp.com/events?q={q}&page={page}&limit={limit}

Parameters

Name	Type	Description
q	object (optional)	Search query. See Search Parameters
page	number (optional)	Number of the page requested
limit	number (optional)	Max number of results per page (default 50, maximum 100)

Get event


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/events/${EVENT_ID}'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/events/evt_55c8c149"
  },
  "id": "evt_55c8c149",
  "type": "assign",
  "emitted_at": 1453770984.123,
  "source": {
    "_meta": {
      "type": "rule"
    },
    "data": {
      "_links": {
        "self": "https://api2.frontapp.com/rules/rul_55c8c149"
      },
      "id": "rul_55c8c149",
      "name": "Important deliveries",
      "actions": [
        "Assign to Leela Turanga"
      ]
    }
  },
  "target": {
    "_meta": {
      "type": "teammate"
    },
    "data": {
      "_links": {
        "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
        "related": {
          "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
          "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
        }
      },
      "id": "tea_55c8c149",
      "email": "leela@planet-express.com",
      "username": "leela",
      "first_name": "Leela",
      "last_name": "Turanga",
      "is_admin": true,
      "is_available": true
    }
  },
  "conversation": {
    "_links": {
      "self": "https://api2.frontapp.com/conversations/cnv_55c8c149",
      "related": {
        "events": "https://api2.frontapp.com/conversations/cnv_55c8c149/events",
        "followers": "https://api2.frontapp.com/conversations/cnv_55c8c149/followers",
        "messages": "https://api2.frontapp.com/conversations/cnv_55c8c149/messages",
        "comments": "https://api2.frontapp.com/conversations/cnv_55c8c149/comments",
        "inboxes": "https://api2.frontapp.com/conversations/cnv_55c8c149/inboxes"
      }
    },
    "id": "cnv_55c8c149",
    "subject": "You broke my heart, Hubert.",
    "status": "archived",
    "assignee": {
      "_links": {
        "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
        "related": {
          "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
          "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
        }
      },
      "id": "tea_55c8c149",
      "email": "leela@planet-express.com",
      "username": "leela",
      "first_name": "Leela",
      "last_name": "Turanga",
      "is_admin": true,
      "is_available": true
    },
    "recipient": {
      "_links": {
        "related": {
          "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
        }
      },
      "handle": "calculon@momsbot.com",
      "role": "to"
    },
    "tags": [
      {
        "_links": {
          "self": "https://api2.frontapp.com/tags/tag_55c8c149",
          "related": {
            "conversations": "https://api2.frontapp.com/tags/tag_55c8c149/conversations"
          }
        },
        "id": "tag_55c8c149",
        "name": "Robots"
      }
    ],
    "last_message": {
      "_links": {
        "self": "https://api2.frontapp.com/messages/msg_55c8c149",
        "related": {
          "conversation": "https://api2.frontapp.com/conversations/cnv_55c8c149",
          "message_replied_to": "https://api2.frontapp.com/messages/msg_1ab23cd4"
        }
      },
      "id": "msg_55c8c149",
      "type": "email",
      "is_inbound": true,
      "created_at": 1453770984.123,
      "blurb": "Anything less than immortality is a...",
      "author": {
        "_links": {
          "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
          "related": {
            "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
            "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
          }
        },
        "id": "tea_55c8c149",
        "email": "leela@planet-express.com",
        "username": "leela",
        "first_name": "Leela",
        "last_name": "Turanga",
        "is_admin": true,
        "is_available": true
      },
      "recipients": [
        {
          "_links": {
            "related": {
              "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
            }
          },
          "handle": "calculon@momsbot.com",
          "role": "to"
        }
      ],
      "body": "Anything less than immortality is a complete waste of time.",
      "text": "Anything less than immortality is a complete waste of time.",
      "attachments": [
        {
          "filename": "attachment.jpg",
          "url": "https://api2.frontapp.com/download/fil_55c8c149",
          "content_type": "image/jpeg",
          "size": 10000,
          "metadata": {
            "is_inline": true,
            "cid": "123456789"
          }
        }
      ],
      "metadata": {}
    },
    "created_at": 1453770984.123
  }
}

Fetches the full details of an event.

HTTP Request

GET https://api2.frontapp.com/events/{event_id}

Parameters

Name	Type	Description
event_id	string	The ID of the requested event

Analytics

To get statistics about activities happening in Front, you need to requests the correspondig metrics of the analytics.

Each metrics can be either:

A scalar: this is a single value (a number, duration, percentage or string).
A table: this is a set of different values for a set of resources.
A time graph: this is a unique value decomposed in multiple values over the requested time range.

Scalar metrics available:

Name	Type	Description
`avg_conversations_per_day`	Number	Average number of conversations occuring per day
`avg_first_response_time`	Duration	Average time for your teammates to send the first reply
`avg_replies_to_resolve`	Number	Average number of replies to resolve a conversation
`avg_resolution_time`	Duration	Average time for a conversation to be resolved
`avg_response_time`	Duration	Average time for your teammate to reply to a message
`busiest_day`	String	Name of the day where you receive the most messages
`busiest_time`	String	Hour of the day where you receive the most messages
`num_active_conversations`	Number	Number of conversation which received at least one message
`num_customers_helped`	Number	Number of unique customer with which your teammates interacted
`num_messages_received`	Number	Total number of messages received
`num_new_conversations`	Number	Number of new conversations
`num_replies_sent`	Number	Number of replies sent
`pct_resolved_on_first_reply`	Percentage	Percentage of conversations resolved on the first reply

Table metrics available:

Name	Resource type	Values
`customers_table`	List of customers	Number of messages, average first reply time, average response time and average resolution time
`first_response_histo`	List of duration	Percentage of first responses sent for each duration
`resolution_histo`	List of duration	Percentage of resolved conversation for each duration
`response_histo`	List of duration	Percentage of responses sent for each duration
`tags_table`	List of tags	Number of messages, average number of messages per conversation, number of archived conversations, number of open conversations, total number of conversations
`team_table`	List of teammates	Number of conversation, average number of messages per conversation, average time to react to a conversation, number of messages, number of sent messages, number of replies sent, number of messages composed
`top_conversations_table`	Top 3 teammates	Number of conversations
`top_reaction_time_table`	Top 3 teammates	Time to react to a conversation
`top_replies_table`	Top 3 teammates	Number of replies sent

Time graph metrics available:

Name	Description
`customers_helped_graph`	Number of unique customer which received at least one message
`first_response_graph`	Average time for your teammate to send the first reply
`messages_received_graph`	Number of messages received
`new_conversations_graph`	Number of new conversations
`replies_sent_graph`	Number of replies sent
`resolution_graph`	Average time to resolve a conversation
`response_graph`	Average time for your teammate to reply to a message

Each metrics contains the value for the requested time period (in the field named v) as well as the value for the previous period (in the field named p).

Depending on the date range you request the analytics, it can take some time to process it. This is why you might need to send multiple requests to get the results. To help you estimate the remaining time, the server response will contain a progress field containing a number ranging from 0 to 100 which isthe percentage of the analytics processed.

Get analytics


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/analytics/?inbox_ids=${INBOX_IDS}&tag_ids=${TAG_IDS}&start=${START}&end=${END}&timezone=${TIMEZONE}&metrics=${METRICS}'

Response 200

{
  "status": "pending",
  "progress": 42,
  "metrics": [
    {
      "id": "avg_conversations_per_day",
      "metric_type": "scalar",
      "t": "num",
      "v": 42,
      "p": 24
    },
    {
      "id": "first_response_histo",
      "metric_type": "table",
      "columns": [
        {
          "id": "time",
          "label": "Time",
          "type": "num"
        },
        {
          "id": "pct_replies",
          "label": "Replies %",
          "type": "num"
        }
      ],
      "rows": [
        [
          {
            "t": "str",
            "v": "< 15mn",
            "p": "< 15mn"
          },
          {
            "t": "pct",
            "v": "12",
            "p": "50"
          }
        ]
      ]
    },
    {
      "id": "first_response_graph",
      "metric_type: `time_graph`": "",
      "vals": [
        {
          "t": "dur",
          "v": 42,
          "p": 24,
          "label": "January",
          "start": 1451785860,
          "end": 1454464260
        }
      ]
    }
  ]
}

Fetches the metrics correspondig to the parameters.

HTTP Request

GET https://api2.frontapp.com/analytics/?inbox_ids={inbox_ids}&tag_ids={tag_ids}&start={start}&end={end}&timezone={timezone}&metrics={metrics}

Parameters

Name	Type	Description
inbox_ids	array (optional)	List of inbox IDs to include in the generated analytics
tag_ids	array (optional)	List of tag IDs to include in the generated analytics
start	number	Timestamp from which the analytics will start
end	number	Timestamp from which the analytics will end
timezone	string (optional)	Name of the timezone to format the dates. If omitted, the export will use UTC.
metrics	array	List of the metrics to include in the analytics

Exports

Name Type Description

_links object See Response body Structure - Links

_links.self string URL of the export URL

id string Unique identifier for the export.

status enum Status of the export.

progress number Number ranging from 0 to 100 corresponding to the percentage of the export processed.

url string (optional) URL of the generated export. Will be null until the status is “done”.

filename string (optional) Name of the file of the generated export. Will be null until the status is “done”.

size number Size (in bytes) of the export file.

created_at number Date at which the export has been created.

query Export to create Query data used to generate the export.

Front can generate exports of your data for a specific timeframe and/or specific inboxes, teammates or tags.

Since an export takes some time to process, it has a status which can be either:

pending when the export is still generating
done once the export has been generated
failed in case the generation failed

Once the export has been generated, you can download it with its url.

Format

Exports are formatted as a CSV files. The export will contain 1 line per message received in the given time period.

If a message appears in multiple inboxes, it will appear once for each inbox.

Below is table of the field names & descriptions that will be included in the export.

Name	Desctiption
Message ID	Internal Front ID of the message
Conversation ID	Internal Front ID of the entire conversation
Direction	Either `Inbound` or `Outbound`
Status	Status of the conversation: `unassigned`, `assigned`, `archived`, or `trashed`.
Inbox	Name of the inbox where the message was initially sent. If the message appeared in multiple inboxes, it will appear multiple times.
Message Date	`YYYY-MM-DD HH:mm:ss` format, in the requested timezone.
Response time	Duration (in seconds) between an inbound message and the next outbound message in the same conversation.
Handle time	Total duration (in seconds) that a contact was kept waiting for a reply from the team during an assignment. Metric is calculated per assignment.
Assignee	Username of the assignee, if any
Contact name	Contact’s first & last name
Contact handle	Contact’s email address, twitter handle, or phone number - depending on the source of the message.
Extract	Sample of the message
Tags	Tags attached to the conversation.

Timezone

All dates in the the export are presented in the same timezone. If the export was requested from the app (by clicking on “Request Export”), it will be in the timezone of the user. If the export is requested with the API, the timezone can be manually defined (or defaults to UTC).

Response time

Response time is always calculated from the point of view of a customer: how did it take for your company to reply?

Most of the time, the response time is the difference between an inbound message from a customer and the next reply from your team.

If your team replies several times to the same message, the response time is the time since the previous reply.

Assignments and Handle time

Most of the time, only one discussion happens within a conversation. That is: a customer will open a conversation to ask a specific thing and if they want to ask another one, they will open a new discussion.

However, this is not always the case:

A customer might decide to reply to an existing conversation even if they are asking for something new.
Several teammates might write in one conversation.

Because of this, Front will compute a handle time to the last message if:

the conversation is reassigned to a different teammate.
the conversation is inactive for 4 days.

List exports


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/exports?page=${PAGE}&limit=${LIMIT}'

Response 200

{
  "_pagination": {
    "limit": 50
  },
  "_links": {
    "self": "https://api2.frontapp.com/exports"
  },
  "_results": [
    {
      "_links": {
        "self": "https://api2.frontapp.com/exports/exp_55c8c149"
      },
      "id": "exp_55c8c149",
      "status": "pending",
      "progress": 42,
      "url": "http://exports.frontapp.com/planet-express/export.csv",
      "filename": "export.csv",
      "size": 1000,
      "created_at": 1453770984.123,
      "query": {
        "inbox_id": "alt:address:team@planet-express.com",
        "teammate_id": "alt:email:fry@planet-express.com",
        "start": 1428889003,
        "end": 1428889008,
        "timezone": "America/New_York",
        "should_export_events": false
      }
    }
  ]
}

Lists all the exports generated in your company.

HTTP Request

GET https://api2.frontapp.com/exports?page={page}&limit={limit}

Parameters

Name	Type	Description
page	number (optional)	Number of the page requested
limit	number (optional)	Max number of results per page (default 50, maximum 100)

Get export


curl --include \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
'https://api2.frontapp.com/exports/${EXPORT_ID}'

Response 200

{
  "_links": {
    "self": "https://api2.frontapp.com/exports/exp_55c8c149"
  },
  "id": "exp_55c8c149",
  "status": "pending",
  "progress": 42,
  "url": "http://exports.frontapp.com/planet-express/export.csv",
  "filename": "export.csv",
  "size": 1000,
  "created_at": 1453770984.123,
  "query": {
    "inbox_id": "alt:address:team@planet-express.com",
    "teammate_id": "alt:email:fry@planet-express.com",
    "start": 1428889003,
    "end": 1428889008,
    "timezone": "America/New_York",
    "should_export_events": false
  }
}

Fetches the information of an export.

HTTP Request

GET https://api2.frontapp.com/exports/{export_id}

Parameters

Name	Type	Description
export_id	string	ID of the requested export

Create export


curl --include \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer {your_token}" \
     --header "Accept: application/json" \
     --data-binary "{
  \"inbox_id\": \"alt:address:team@planet-express.com\",
  \"teammate_id\": \"alt:email:fry@planet-express.com\",
  \"start\": 1428889003,
  \"end\": 1428889008,
  \"timezone\": \"America/New_York\",
  \"should_export_events\": false
}" \
'https://api2.frontapp.com/exports'

Response 201

{
  "_links": {
    "self": "https://api2.frontapp.com/exports/exp_55c8c149"
  },
  "id": "exp_55c8c149",
  "status": "pending",
  "progress": 42,
  "url": "http://exports.frontapp.com/planet-express/export.csv",
  "filename": "export.csv",
  "size": 1000,
  "created_at": 1453770984.123,
  "query": {
    "inbox_id": "alt:address:team@planet-express.com",
    "teammate_id": "alt:email:fry@planet-express.com",
    "start": 1428889003,
    "end": 1428889008,
    "timezone": "America/New_York",
    "should_export_events": false
  }
}

Requests the creation of a new export

HTTP Request

POST https://api2.frontapp.com/exports

Body

Name	Type	Description
inbox_id	string (optional)	ID of the inbox to export the analytics for. If omitted, the export will contain all the inboxes.
teammate_id	string (optional)	ID of the teammate to export the analytics for. If omitted, the export will contain all the teammates.
tag_id: `tag_55c8c149`	string (optional)	ID the tag to export the analytics for. If omitted, the export will contain all the tags.
start	number	Start time of the data to include in the export.
end	number	End time of the data to include in the export.
timezone	string (optional)	Name of the timezone to format the dates. If omitted, the export will use UTC.
should_export_events	boolean (optional)	Whether to export all the events or only messages. Default to `false`.

Attachments

Name Type Description

filename string Name of the attached file

url string URL to download the attached file

content_type string Content type of the attached file

size number Size (in byte) of the attached file

metadata object

metadata.is_inline boolean Whether or not the attachment is part of the message body

metadata.cid string (optional) Unique identifier used to link an attachment to where it is used in the message body

When a message has attached files, the attachments array will contain the information needed to retrieve those files.

If the attachment is inline (ie: an image in the body of an email), the property metadata.cid will help you retrieve the HTML tag corresponding to the attachmens in the body of the message.

Download attachment

In the attachment object, the property url can be used to download the attached file.

Just like any other API endpoint, the download request should be authenticated.
The response however will not be a JSON object but the content of the file with the correct headers so that you can save it.

File upload

Even though all the API is designed to work with JSON, some endpoints supports file upload:

Sending a new message
Replying to a conversation
Receiving a custom message
Importing a message
Create a contact
Update a contact

Send multipart request

Example of a HTTP request to send a new message with an attachment

POST /channels/{channel_id}/messages HTTP/1.1
Host: api2.frontapp.com
Accept: application/json
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=----RandomBoundaryString

------RandomBoundaryString
Content-Disposition: form-data; name="author_id"

alt:email:leela@planet-exress.com
------RandomBoundaryString
Content-Disposition: form-data; name="to[0]"

calculon@momsbot.com
------RandomBoundaryString
Content-Disposition: form-data; name="subject"

Good news everyone!
------RandomBoundaryString
Content-Disposition: form-data; name="body"

Why is Zoidberg the only one still alone?
------RandomBoundaryString
Content-Disposition: form-data; name="attachments[0]"; filename="logo.jpg"
Content-Type: image/jpeg

<binary data>
------RandomBoundaryString
Content-Disposition: form-data; name="options[archive]"

true
------RandomBoundaryString--

Example of a HTTP request to update the avatar of a contact

PATCH /contacts/{contact_id} HTTP/1.1
Host: api2.frontapp.com
Authorization: Bearer <token>
Content-Type: multipart/form-data; boundary=----RandomBoundaryString

------RandomBoundaryString
Content-Disposition: form-data; name="avatar"; filename="your-avatar.png"
Content-Type: image/png

<binary data>
------RandomBoundaryString--

When you want to send files through the API, your request needs to be sent using the Content-Type HTTP header set to multipart/form-data.

The JSON data you would normally send in the request body needs to be split in multiple form fields (one for each property) named after the property key. If the property is an array, the name should include the index of the data (ie: {"to": [email1@example.com, email1@example.com]} would be split in two fields named to[0], to[1]).

Custom channels

A custom channel lets you control how messages are received and sent via HTTP calls. You can use custom channels to integrate Front with platforms that are not officially supported.

Create a custom channel

Go to Settings > Inboxes
Click on “Add an inbox” and choose the Custom type
Choose a name for your inbox
Define a callback URL

Receive messages

See Receive a custom message endpoint documentation.

Sending messages

In case of a teammate sending a message, this is what the request body your endpoint would receive:

{
  "_links": {
    "self": "https://api2.frontapp.com/messages/msg_55c8c149",
    "related": {
      "conversation": "https://api2.frontapp.com/conversations/cnv_55c8c149",
      "message_replied_to": "https://api2.frontapp.com/messages/msg_1ab23cd4"
    }
  },
  "id": "msg_55c8c149",
  "type": "custom",
  "is_inbound": false,
  "created_at": 1453770984.123,
  "blurb": "Anything less than immortality is a...",
  "author": {
    "_links": {
      "self": "https://api2.frontapp.com/teammates/tea_55c8c149",
      "related": {
        "inboxes": "https://api2.frontapp.com/teammates/tea_55c8c149/inboxes",
        "conversations": "https://api2.frontapp.com/teammates/tea_55c8c149/conversations"
      }
    },
    "id": "tea_55c8c149",
    "email": "leela@planet-express.com",
    "username": "leela",
    "first_name": "Leela",
    "last_name": "Turanga",
    "is_admin": true,
    "is_available": true
  },
  "recipients": [
    {
      "handle": "calculon@momsbot.com",
      "role": "to",
      "_links": {
        "related": {
          "contact": "https://api2.frontapp.com/contacts/ctc_55c8c149"
        }
      }
    }
  ],
  "body": "Anything less than immortality is a complete waste of time.",
  "text": "Anything less than immortality is a complete waste of time.",
  "attachments": [],
  "metadata": {}
}

Whenever a message is sent from Front (either by a rule or by a teammate), a POST HTTP request will be issued to the callback URL you defined. The request body will contain the data of the message sent just like if fetched it.

The request body will be signed using your API secret so you can validate that it came from Front (cf: Checkin data integrity).

Webhooks

A webhook allows you to be automatically notified when something happens in Front without having to constantly poll the API.
For each event happening in Front, your webhook will receive a POST HTTP request with the event preview JSON representation in the request body.

Setup

For more information about how to enable and setup a webhook, please refer to our help center.

Checking data integrity

const crypto = require('crypto');
const apiSecret = 'YOUR_API_SECRET';

function validateFrontSignature(data, signature) {
    var hash = crypto.createHmac('sha1', apiSecret)
                     .update(JSON.stringify(data))
                     .digest('base64');

   return hash === signature;
}

For security reason and since the webhook URL is open to the public, you should not trust any incoming requests that it receives. Each requests we send to your webhook URLs will contain an X-Front-Signature header generated using the request body and your API Secret.

To validate that the data came from Front, you need to calculate the base64 encoded HMAC hash of the request body using sha1 algorithm and your API secret as the key. If the value matches the signature in the header, you can be sure the request was sent from Front.

You can get your API secret by going to Settings > API & Integrations > API.

OAuth

OAuth 2.0 is a protocol that lets external applications request authorization to API access in a secure way.

Each OAuth application is assigned a unique Client ID and Client Secret which will be used in the authorization flow. The Client Secret should never be shared.
If you want to create an OAuth application, please contact us on api@frontapp.com to get your credentials.

Front’s OAuth implementation only supports the authorization code grant type which define a flow to get a temporary authorization token which can then be exchanged to get an API token.

1. Request authorization

GET /oauth/authorize?response_type=code&client_id={clientId}&redirect_uri={redirectURI} HTTP/1.1
Host: app.frontapp.com

You should replace “{clientID}” and “{redirectURI}” by the values of your OAuth application.

To request Front API access, you need to redirect the user to https://app.frontapp.com/oauth/authorize.

Parameters

Name	Type	Description
response_type	string	Must be set to `code`.
client_id	string	Client ID of your OAuth application.
redirect_uri	string	The URL in your application where users will be redirected after authorization.
state	string (optional)	Used to protect against cross-site request forgery attacks.

2. Get an authorization code

GET /example_path?code={authorizationCode}&state={state} HTTP/1.1
Host: yoursite.example.com

The HTTP request will depend on the param redirect_uri specified in the authorization request.

If the user accepts the authorization request, Front will redirect him back to the redirect URL specified in the first step.
The request will contain a code parameter as well as the state you provided in the first step.

If the states don’t match, you should consider the request as unsecure and the process should be aborted.

Parameters

Name	Type	Description
code	string	Temporary authorization code to exchange for an API token.
state	string (optional)	State provided in the authorization request.

3. Exchange authorization code

POST /oauth/token HTTP/1.1
Host: app.frontapp.com
Authorization: Basic <your_basic_credentials>

Response 200

{
    "access_token": "",
    "token_type": "Bearer"
}

Once your application receive the temporary authorization code, you need to exchanged it for an API token by sending a POST HTTP request to https://app.frontapp.com/oauth/token.

Your request MUST be authentified with Basic authentication using your OAuth application Client ID and Client Secret.

Front OAuth server response will include the API token in the access_token param.

Parameters

Name	Type	Description
code	string	The temporary authorization code received in step 2.
redirect_uri	string	The URL in your application where users will be redirected after authorization.
grant_type	string	The grant type used to get the authorization code. Needs to be `authorization_code`

Name	Type	Description
author	Teammate	Teammate who wrote the note
body	string	Content of the note
created_at	number	Date at which the note have been created

Name	Type	Description
tag_id	string	ID of the requested tag
q	object (optional)	Search query. See Search Parameters
page	number (optional)	Number of the page requested
limit	number (optional)	Max number of results per page (default 50, maximum 100)

Name	Type	Description
filename	string	Name of the attached file
url	string	URL to download the attached file
content_type	string	Content type of the attached file
size	number	Size (in byte) of the attached file
metadata	object
metadata.is_inline	boolean	Whether or not the attachment is part of the message body
metadata.cid	string (optional)	Unique identifier used to link an attachment to where it is used in the message body