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