API Authentication

MailTrixy uses Laravel Sanctum personal access tokens for API authentication. This page covers how to create, manage, and use API tokens.

Creating API Tokens

API tokens can be created from the MailTrixy dashboard or programmatically. Each token is bound to a specific user and workspace.

Via Dashboard

1. Navigate to Settings → API Tokens in your workspace.
2. Click Create New Token.
3. Enter a descriptive name for the token (e.g., "CRM Integration", "Zapier Connection").
4. Select the scopes (permissions) the token should have.
5. Click Generate Token.
6. Copy the token immediately. It will only be displayed once for security reasons.

Via API

curl -X POST https://your-domain.com/api/v1/tokens \
  -H "Authorization: Bearer mb_existing-token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Integration Token",
    "scopes": ["contacts", "conversations", "campaigns"]
  }'

Response:

{
    "success": true,
    "data": {
        "token": "mb_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
        "name": "My Integration Token",
        "scopes": ["contacts", "conversations", "campaigns"],
        "expires_at": "2026-03-25T14:00:00Z"
    }
}

Token Scopes

Scopes determine which API endpoints a token can access. Always assign the minimum required scopes for your integration.

Scope	Permissions	Endpoints
contacts	Read, create, update, and delete contacts and contact groups	/api/v1/contacts/*
conversations	Read conversations, send replies, assign, and close	/api/v1/conversations/*
campaigns	Create, update, and send campaigns	/api/v1/campaigns/*
workflows	Create, update, activate, and pause workflows	/api/v1/workflows/*
knowledge-base	Manage knowledge bases, documents, and website scrapes	/api/v1/knowledge-bases/*
ai	Generate AI replies, analyze sentiment, chat with AI	/api/v1/ai/*
analytics	Read analytics data, reports, and usage statistics	/api/v1/analytics/*
canned-responses	Manage canned response templates	/api/v1/canned-responses/*

Token Prefix

All MailTrixy API tokens are prefixed with mb_ to make them easily identifiable in logs, configuration files, and code. This helps prevent accidentally using tokens from other services and makes it easy to scan for leaked credentials.

# Token format
mb_[40-character-random-string]

# Example
mb_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0

Token Expiration

By default, API tokens expire after 4 hours from the time of creation. This can be configured in the application settings.

• Default expiration: 4 hours
• Maximum expiration: 30 days (configurable by admin)
• No expiration: Not recommended, but can be enabled by admin for service-to-service integrations
• Refresh: Tokens cannot be refreshed. Create a new token before the current one expires.

// config/sanctum.php
'expiration' => 240, // minutes (4 hours)

When a token expires, the API returns a 401 Unauthenticated response. Your integration should handle this by creating a new token.

Example Requests

List Contacts

curl -X GET "https://your-domain.com/api/v1/contacts?page=1&per_page=10" \
  -H "Authorization: Bearer mb_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json"

Create a Contact

curl -X POST "https://your-domain.com/api/v1/contacts" \
  -H "Authorization: Bearer mb_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jane@example.com",
    "company": "Acme Corp",
    "phone": "+1-555-0123",
    "tags": ["lead", "enterprise"],
    "custom_fields": {
        "department": "Engineering",
        "deal_value": 50000
    }
  }'

Reply to a Conversation

curl -X POST "https://your-domain.com/api/v1/conversations/42/reply" \
  -H "Authorization: Bearer mb_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "body": "Thank you for reaching out. We will get back to you shortly.",
    "channel": "email"
  }'

Trigger a Campaign Send

curl -X POST "https://your-domain.com/api/v1/campaigns/15/send" \
  -H "Authorization: Bearer mb_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Accept: application/json"

Get AI Sentiment Analysis

curl -X POST "https://your-domain.com/api/v1/ai/sentiment" \
  -H "Authorization: Bearer mb_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "text": "I am very frustrated with the delayed response to my support ticket."
  }'

Response:

{
    "success": true,
    "data": {
        "sentiment": "negative",
        "score": -0.78,
        "urgency": "high",
        "emotions": ["frustration", "disappointment"]
    }
}