# API Overview

MailTrixy provides a comprehensive REST API that allows you to integrate with external services, build custom interfaces, and automate your email management workflows programmatically.

## Base URL

All API requests are made to the following base URL:

    https://your-domain.com/api/v1

All API endpoints are prefixed with `/api/v1`. The API follows RESTful conventions with JSON request and response bodies.

## Authentication

The API uses Laravel Sanctum personal access tokens for authentication. Every request must include a valid API token in the `Authorization` header.

    Authorization: Bearer mb_your-api-token-here

Tokens are prefixed with `mb_` for easy identification. Each token is scoped to a specific workspace and user, and expires after 4 hours by default. See the API Authentication page for details on creating and managing tokens.

## Rate Limiting

API requests are rate-limited to protect system resources and ensure fair usage across all workspaces. Rate limits vary by scope.

Scope | Limit | Window
--- | --- | ---
General endpoints | 60 requests | Per minute
Contact operations | 120 requests | Per minute
Campaign sending | 10 requests | Per minute
AI endpoints | 30 requests | Per minute
Analytics queries | 20 requests | Per minute

Rate limit information is included in response headers:

    X-RateLimit-Limit: 60
    X-RateLimit-Remaining: 58
    X-RateLimit-Reset: 1711353600

## Response Format

All API responses are returned in JSON format with a consistent structure.

### Successful Response

    {
        "success": true,
        "data": {
            "id": 1,
            "name": "John Doe",
            "email": "john@example.com"
        },
        "meta": {
            "timestamp": "2026-03-25T10:00:00Z"
        }
    }

### Collection Response

    {
        "success": true,
        "data": [
            { "id": 1, "name": "John Doe" },
            { "id": 2, "name": "Jane Smith" }
        ],
        "meta": {
            "current_page": 1,
            "per_page": 25,
            "total": 150,
            "last_page": 6
        }
    }

### Error Response

    {
        "success": false,
        "error": {
            "code": "VALIDATION_ERROR",
            "message": "The given data was invalid.",
            "details": {
                "email": ["The email field is required."]
            }
        }
    }

## Pagination

List endpoints return paginated results. You can control pagination with the following query parameters:

Parameter | Default | Description
--- | --- | ---
page | 1 | Page number to retrieve
per_page | 25 | Number of items per page (max 100)
sort_by | created_at | Field to sort results by
sort_order | desc | Sort direction: asc or desc

## Error Codes

HTTP Status | Error Code | Description
--- | --- | ---
400 | BAD_REQUEST | The request body is malformed or missing required fields
401 | UNAUTHENTICATED | Missing or invalid API token
403 | FORBIDDEN | Token lacks the required scope for this endpoint
404 | NOT_FOUND | The requested resource does not exist
422 | VALIDATION_ERROR | Request validation failed with field-level error details
429 | RATE_LIMITED | Rate limit exceeded, retry after the specified window
500 | SERVER_ERROR | An internal server error occurred