Front

Front API integration with managed OAuth. Manage conversations, messages, contacts, tags, inboxes, teammates, and teams. Use this skill when users want to in...

Security Scan

The skill is internally consistent: it proxies Front API calls through Maton (gateway.maton.ai / ctrl.maton.ai) and only requests a single MATON_API_KEY, but that key grants a third party access to your Front data so you should verify and limit trust accordingly.

Purpose & Capability

Name/description (Front API integration with managed OAuth) matches the requested artifact: the SKILL.md documents using a Maton gateway and managed OAuth, and the only required env var is MATON_API_KEY which is required to call that gateway.

Instruction Scope

SKILL.md contains explicit, narrow runtime instructions (HTTP requests to gateway.maton.ai and ctrl.maton.ai, how to list/create/delete connections, and using Maton-Connection header). It does not instruct reading local files, unrelated env vars, or exfiltrating data to unexpected endpoints beyond Maton-controlled URLs.

Install Mechanism

Instruction-only skill with no install spec and no code files — nothing is written to disk or fetched at install time.

Credentials

Only MATON_API_KEY is required which is proportional to using a managed OAuth gateway; however that single key delegates access to Maton (a third party). There is no explanation of required key scope/least-privilege or how Maton stores/uses tokens — this is a privacy/trust consideration rather than a technical mismatch.

Persistence & Privilege

always:false and no install persistence; agent autonomous invocation is allowed (platform default). If the agent is allowed to call skills autonomously, the MATON_API_KEY could be used without interactive consent — consider this when granting the key.

Assessment

This skill appears to do what it says: it proxies Front API calls through Maton and needs MATON_API_KEY. Before installing, verify you trust maton.ai (organization, privacy/security docs), understand that the MATON_API_KEY delegates access to a third party (Maton) which will proxy and store OAuth tokens for your Front accounts, and use least-privilege / short-lived credentials if possible. Monitor API usage after enabling, rotate the key if you suspect misuse, and if you prefer direct control over credentials, consider using a direct Front integration instead of a third-party gateway.

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

Quick Start

# List inboxes
python <<'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 <<'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 <<'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 <<'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 <<'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 <<'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": "[e-mail]",
      "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": "[e-mail]",
      "send_as": "[e-mail]",
      "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": "[e-mail]",
      "address": "[e-mail]",
      "send_as": "[e-mail]",
      "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": "[e-mail]"
      },
      "recipient": {
        "handle": "[e-mail]"
      },
      "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": "[e-mail]"
  },
  "recipients": [
    {
      "handle": "[e-mail]",
      "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": ["[e-mail]"],
  "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": "[e-mail]"}
      ],
      "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": "[e-mail]"}
  ],
  "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': '[e-mail]'}]
    }
)
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

Status	Meaning
400	Missing Front connection or invalid request
401	Invalid or missing Maton API key
403	Insufficient permissions
404	Resource not found
429	Rate limited
4xx/5xx	Passthrough error from Front API

Resources

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