Front

Access the Front API with managed OAuth authentication. Manage conversations, messages, contacts, tags, inboxes, teammates, and teams.

Quick Start

# List inboxes
python \x3C\x3C'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/front/inboxes')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Base URL

https://gateway.maton.ai/front/{native-api-path}

Replace {native-api-path} with the actual Front API endpoint path (e.g., inboxes, conversations, contacts). The gateway proxies requests to api2.frontapp.com and automatically injects your OAuth token.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your Front OAuth connections at https://ctrl.maton.ai.

List Connections

python \x3C\x3C'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=front&status=ACTIVE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Create Connection

python \x3C\x3C'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'front'}).encode()
req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Get Connection

python \x3C\x3C'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Response:

{
  "connection": {
    "connection_id": "4688f416-fdc3-49dc-8871-2d7522e6b808",
    "status": "ACTIVE",
    "creation_time": "2026-04-02T22:15:03.462342Z",
    "last_updated_time": "2026-04-02T22:15:37.297108Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "front",
    "metadata": {}
  }
}

Open the returned url in a browser to complete OAuth authorization.

Delete Connection

python \x3C\x3C'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Specifying Connection

If you have multiple Front connections, specify which one to use with the Maton-Connection header:

python \x3C\x3C'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/front/inboxes')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('Maton-Connection', '4688f416-fdc3-49dc-8871-2d7522e6b808')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection.

API Reference

Company / Me

Get Current Company

GET /front/me

Response:

{
  "_links": {"self": "https://company.api.frontapp.com/me"},
  "name": "Company Name",
  "id": "cmp_12345"
}

Teammates

List Teammates

GET /front/teammates

Response:

{
  "_pagination": {"next": null},
  "_results": [
    {
      "id": "tea_pa3u0",
      "email": "[email protected]",
      "username": "username",
      "first_name": "John",
      "last_name": "Doe",
      "is_admin": true,
      "is_available": true,
      "is_blocked": false,
      "type": "user"
    }
  ]
}

Get Teammate

GET /front/teammates/{teammate_id}

Teams

List Teams

GET /front/teams

Response:

{
  "_pagination": {"next": null},
  "_results": [
    {
      "id": "tim_9p8dk",
      "name": "Customer Support"
    },
    {
      "id": "tim_9p8fc",
      "name": "Sales"
    }
  ]
}

Inboxes

List Inboxes

GET /front/inboxes

Response:

{
  "_pagination": {"next": null},
  "_results": [
    {
      "id": "inb_lzrag",
      "name": "Support",
      "is_private": false,
      "is_public": true,
      "address": "[email protected]",
      "send_as": "[email protected]",
      "type": "smtp"
    }
  ]
}

Get Inbox

GET /front/inboxes/{inbox_id}

Create Inbox

POST /front/inboxes
Content-Type: application/json

{
  "name": "New Inbox",
  "teammate_ids": ["tea_abc123"]
}

Channels

List Channels

GET /front/channels

Response:

{
  "_pagination": {"next": null},
  "_results": [
    {
      "id": "cha_ogobs",
      "name": "[email protected]",
      "address": "[email protected]",
      "send_as": "[email protected]",
      "type": "smtp",
      "is_private": false,
      "is_valid": true
    }
  ]
}

Get Channel

GET /front/channels/{channel_id}

Conversations

List Conversations

GET /front/conversations

Query Parameters:

• q - Search query
• page_token - Pagination token

Response:

{
  "_pagination": {"next": null},
  "_results": [
    {
      "id": "cnv_abc123",
      "subject": "Help with order",
      "status": "open",
      "assignee": {
        "id": "tea_pa3u0",
        "email": "[email protected]"
      },
      "recipient": {
        "handle": "[email protected]"
      },
      "last_message": {
        "body": "Message content..."
      },
      "created_at": 1774828390.948
    }
  ]
}

Get Conversation

GET /front/conversations/{conversation_id}

Update Conversation

PATCH /front/conversations/{conversation_id}
Content-Type: application/json

{
  "assignee_id": "tea_abc123",
  "inbox_id": "inb_xyz789",
  "status": "archived",
  "tag_ids": ["tag_123"]
}

Update Conversation Assignee

PUT /front/conversations/{conversation_id}/assignee
Content-Type: application/json

{
  "assignee_id": "tea_abc123"
}

Messages

Get Message

GET /front/messages/{message_id}

Response:

{
  "id": "msg_abc123",
  "type": "email",
  "is_inbound": true,
  "created_at": 1774828390.948,
  "blurb": "Message preview...",
  "body": "Full message content...",
  "author": {
    "id": "tea_pa3u0",
    "email": "[email protected]"
  },
  "recipients": [
    {
      "handle": "[email protected]",
      "role": "to"
    }
  ]
}

Send Reply

POST /front/conversations/{conversation_id}/messages
Content-Type: application/json

{
  "author_id": "tea_abc123",
  "body": "Thank you for reaching out!",
  "type": "reply"
}

Send New Message

POST /front/channels/{channel_id}/messages
Content-Type: application/json

{
  "author_id": "tea_abc123",
  "to": ["[email protected]"],
  "subject": "Following up",
  "body": "Hi, just following up on your inquiry..."
}

Contacts

List Contacts

GET /front/contacts

Query Parameters:

• q - Search query (email, name, phone)
• page_token - Pagination token

Response:

{
  "_pagination": {"next": null},
  "_results": [
    {
      "id": "crd_54wgwiw",
      "name": "John Doe",
      "description": "",
      "handles": [
        {"source": "email", "handle": "[email protected]"}
      ],
      "groups": [],
      "updated_at": 1774828390.948,
      "is_private": false
    }
  ]
}

Get Contact

GET /front/contacts/{contact_id}

Create Contact

POST /front/contacts
Content-Type: application/json

{
  "name": "Jane Smith",
  "handles": [
    {"source": "email", "handle": "[email protected]"}
  ],
  "description": "VIP customer"
}

Update Contact

PATCH /front/contacts/{contact_id}
Content-Type: application/json

{
  "name": "Jane Smith-Jones",
  "description": "Updated description"
}

Delete Contact

DELETE /front/contacts/{contact_id}

Tags

List Tags

GET /front/tags

Response:

{
  "_pagination": {"next": null},
  "_results": [
    {
      "id": "tag_6v3mzs",
      "name": "Urgent",
      "highlight": "red",
      "description": "High priority items",
      "is_private": false,
      "is_visible_in_conversation_lists": true
    }
  ]
}

Get Tag

GET /front/tags/{tag_id}

Create Tag

POST /front/tags
Content-Type: application/json

{
  "name": "Follow-up",
  "highlight": "blue",
  "description": "Needs follow-up"
}

Update Tag

PATCH /front/tags/{tag_id}
Content-Type: application/json

{
  "name": "Updated Tag Name",
  "highlight": "green"
}

Delete Tag

DELETE /front/tags/{tag_id}

Accounts

List Accounts

GET /front/accounts

Get Account

GET /front/accounts/{account_id}

Create Account

POST /front/accounts
Content-Type: application/json

{
  "name": "Acme Corp",
  "description": "Enterprise customer",
  "domains": ["acme.com"]
}

Update Account

PATCH /front/accounts/{account_id}
Content-Type: application/json

{
  "name": "Acme Corporation",
  "description": "Updated description"
}

Comments

List Conversation Comments

GET /front/conversations/{conversation_id}/comments

Create Comment

POST /front/conversations/{conversation_id}/comments
Content-Type: application/json

{
  "author_id": "tea_abc123",
  "body": "Internal note: Customer is a VIP"
}

Pagination

Front uses cursor-based pagination with _pagination in responses:

{
  "_pagination": {
    "next": "https://api2.frontapp.com/contacts?page_token=abc123"
  },
  "_results": [...]
}

To get the next page, use the page_token parameter:

GET /front/contacts?page_token=abc123

When _pagination.next is null, there are no more results.

Code Examples

JavaScript

const response = await fetch(
  'https://gateway.maton.ai/front/inboxes',
  {
    headers: {
      'Authorization': `Bearer ${process.env.MATON_API_KEY}`
    }
  }
);
const data = await response.json();
console.log(data._results);

Python

import os
import requests

response = requests.get(
    'https://gateway.maton.ai/front/contacts',
    headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
)
contacts = response.json()['_results']

Create Contact and Tag Conversation

import os
import requests

headers = {
    'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}',
    'Content-Type': 'application/json'
}

# Create a contact
contact_resp = requests.post(
    'https://gateway.maton.ai/front/contacts',
    headers=headers,
    json={
        'name': 'New Customer',
        'handles': [{'source': 'email', 'handle': '[email protected]'}]
    }
)
contact = contact_resp.json()

# Tag a conversation
conversation_id = 'cnv_abc123'
requests.patch(
    f'https://gateway.maton.ai/front/conversations/{conversation_id}',
    headers=headers,
    json={'tag_ids': ['tag_urgent']}
)

Notes

• Resource IDs use prefixes: tea_ (teammate), tim_ (team), inb_ (inbox), cha_ (channel), cnv_ (conversation), msg_ (message), crd_ (contact), tag_ (tag), cmp_ (company)
• Timestamps are Unix timestamps (seconds since epoch)
• The API returns _links with related resource URLs
• Responses include _pagination for list endpoints
• The gateway proxies to your company's Front API subdomain (e.g., company.api.frontapp.com)
• IMPORTANT: When using curl commands, use curl -g when URLs contain brackets to disable glob parsing
• IMPORTANT: When piping curl output to jq, environment variables may not expand correctly in some shells

Error Handling

Resources

• Front API Reference
• Front API Authentication
• Front API Rate Limits
• Maton Community
• Maton Support