MailTrixy API

Build powerful integrations with the MailTrixy platform. Manage contacts, conversations, campaigns, and more programmatically.

Quick Start

1. Generate an API Token

Navigate to Settings → Account to create a personal API token. Select the scopes (permissions) your integration needs.

2. Base URL

https://mediacity.co.in/mailtrixy/public/api/v1

3. Make Your First Request

curl -X GET https://mediacity.co.in/mailtrixy/public/api/v1/contacts \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Accept: application/json"

Authentication

All API requests require a valid Bearer token sent in the Authorization header.

Authorization: Bearer your-api-token

Tokens are scoped. When you create a token, you select which API sections it can access:

contacts conversations campaigns workflows knowledge-base temp-mail ai analytics tags canned-responses

Requests to endpoints outside the token's scopes will receive a 403 Forbidden response.

Rate Limiting

API requests are rate-limited to protect service stability. Default limits:

Scope	Limit
General API	600 requests/minute
Import/Export	5 requests/minute
Campaign Send	5 requests/minute
AI Generate Reply	10 requests/minute
AI Analyze Sentiment	20 requests/minute
KB Scrape	3 requests/minute

Rate limit headers are included in every response:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 597
Retry-After: 42  // only when rate limited (429)

Errors

The API uses standard HTTP status codes. Errors return a JSON body with details:

Code	Meaning
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing token
403	Forbidden - Token lacks required scope
404	Not Found - Resource does not exist
422	Validation Error - Check the errors object
429	Too Many Requests - Rate limit exceeded
500	Server Error - Unexpected failure

{
  "message": "Contact not found."
}

// Validation errors (422)
{
  "errors": {
    "email": ["The email field is required."]
  }
}

Contacts

Manage your contact database. Requires contacts scope.

List contacts with search, filters, and pagination.

Parameters

Name	Type	Required	Description
search	string	No	Search by name, email, or company
status	string	No	Filter: active, inactive, unsubscribed
tag_id	integer	No	Filter by tag ID
country	string	No	Filter by country
min_score	integer	No	Minimum lead score (0-100)
max_score	integer	No	Maximum lead score (0-100)
sort_by	string	No	Sort field: first_name, last_name, email, company, lead_score, created_at, last_contacted_at
sort_dir	string	No	asc or desc (default: desc)
per_page	integer	No	Results per page (max 100, default 25)

Example Request

curl -X GET 'https://mediacity.co.in/mailtrixy/public/api/v1/contacts?search=john&per_page=10' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

Example Response

{
  "data": [
    {
      "id": 1,
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone": "+1234567890",
      "company": "Acme Inc",
      "lead_score": 75,
      "status": "active",
      "tags": [{"id": 1, "name": "VIP"}],
      "created_at": "2026-03-01T10:00:00Z"
    }
  ],
  "links": { "first": "...", "last": "...", "prev": null, "next": "..." },
  "meta": { "current_page": 1, "last_page": 5, "per_page": 10, "total": 48 }
}

Create a new contact.

Parameters

Name	Type	Required	Description
first_name	string	Yes	Contact first name (max 255)
last_name	string	No	Contact last name
email	string	Yes	Valid email address
phone	string	No	Phone number
company	string	No	Company name
job_title	string	No	Job title
city	string	No	City
country	string	No	Country
lead_score	integer	No	Lead score (0-100)
custom_fields	object	No	Custom field key-value pairs
tag_ids	array	No	Array of tag IDs to assign

Example Request

curl -X POST 'https://mediacity.co.in/mailtrixy/public/api/v1/contacts' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"first_name":"Jane","email":"[email protected]","company":"Acme"}'

Example Response

{
  "data": {
    "id": 42,
    "first_name": "Jane",
    "last_name": null,
    "email": "[email protected]",
    "company": "Acme",
    "lead_score": 0,
    "status": "active",
    "tags": [],
    "created_at": "2026-03-22T14:30:00Z"
  }
}

Retrieve a single contact by ID.

Example Request

curl -X GET 'https://mediacity.co.in/mailtrixy/public/api/v1/contacts/42' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

Example Response

{
  "data": {
    "id": 42,
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "[email protected]",
    "conversations_count": 12,
    "deals_count": 3
  }
}

Update a contact. Only send fields you want to change.

Parameters

Name	Type	Required	Description
first_name	string	No	Contact first name
email	string	No	Valid email address
status	string	No	active, inactive, or unsubscribed
tag_ids	array	No	Replace all tags with these IDs

Example Request

curl -X PUT 'https://mediacity.co.in/mailtrixy/public/api/v1/contacts/42' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"lead_score":90,"status":"active"}'

Example Response

{
  "data": {
    "id": 42,
    "first_name": "Jane",
    "lead_score": 90,
    "status": "active"
  }
}

Soft-delete a contact.

Example Request

curl -X DELETE 'https://mediacity.co.in/mailtrixy/public/api/v1/contacts/42' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Example Response

204 No Content

Import contacts from a CSV file. Rate limited to 5 req/min.

Parameters

Name	Type	Required	Description
file	file	Yes	CSV/XLSX file (max 10MB). Headers: first_name, last_name, email, phone, company, etc.

Example Request

curl -X POST 'https://mediacity.co.in/mailtrixy/public/api/v1/contacts/import' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -F '[email protected]'

Example Response

{
  "data": {
    "imported": 142,
    "skipped": 3,
    "errors": ["Row 15: invalid email 'not-an-email'"]
  }
}

Export all contacts as a streamed CSV download. Rate limited to 5 req/min.

Example Request

curl -X GET 'https://mediacity.co.in/mailtrixy/public/api/v1/contacts/export' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -o contacts.csv

Example Response

Binary CSV file stream

Conversations

Manage inbox conversations. Requires conversations scope.

List conversations with filters and pagination.

Parameters

Name	Type	Required	Description
status	string	No	Filter: open, closed, snoozed
channel	string	No	Filter by channel: email, chat, whatsapp, sms
assigned_to	integer	No	Filter by assigned user ID
contact_id	integer	No	Filter by contact ID
per_page	integer	No	Results per page (max 100)

Example Request

curl -X GET 'https://mediacity.co.in/mailtrixy/public/api/v1/conversations?status=open' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

Example Response

{
  "data": [
    {
      "id": 1,
      "subject": "Billing question",
      "status": "open",
      "channel": "email",
      "contact": {"id": 5, "email": "[email protected]"},
      "assigned_to": {"id": 2, "name": "Agent Smith"},
      "last_message_at": "2026-03-22T09:30:00Z"
    }
  ],
  "meta": {"current_page": 1, "total": 24}
}

Send a reply to a conversation.

Parameters

Name	Type	Required	Description
body	string	Yes	Reply message body (HTML supported)
internal	boolean	No	If true, add as internal note (not sent to contact)

Example Request

curl -X POST 'https://mediacity.co.in/mailtrixy/public/api/v1/conversations/1/reply' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"body":"Thanks for reaching out! We will look into this."}'

Example Response

{
  "data": {
    "id": 145,
    "conversation_id": 1,
    "body": "Thanks for reaching out! We will look into this.",
    "type": "reply",
    "created_at": "2026-03-22T14:30:00Z"
  }
}

Assign a conversation to a team member.

Parameters

Name	Type	Required	Description
user_id	integer	Yes	User ID to assign the conversation to

Example Request

curl -X POST 'https://mediacity.co.in/mailtrixy/public/api/v1/conversations/1/assign' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"user_id":3}'

Example Response

{
  "data": {"id": 1, "assigned_to": {"id": 3, "name": "Agent Jones"}}
}

Close a conversation.

Example Request

curl -X POST 'https://mediacity.co.in/mailtrixy/public/api/v1/conversations/1/close' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Example Response

{
  "data": {"id": 1, "status": "closed"}
}

Campaigns

Create and manage email campaigns. Requires campaigns scope.

List campaigns with filters.

Parameters

Name	Type	Required	Description
status	string	No	Filter: draft, scheduled, sending, sent, paused
type	string	No	Filter by campaign type
search	string	No	Search by name or subject

Example Request

curl -X GET 'https://mediacity.co.in/mailtrixy/public/api/v1/campaigns?status=sent' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

Example Response

{
  "data": [
    {
      "id": 1,
      "name": "March Newsletter",
      "subject": "What is new in March",
      "status": "sent",
      "sent_count": 1250,
      "open_rate": 34.5,
      "click_rate": 8.2,
      "created_at": "2026-03-01T08:00:00Z"
    }
  ]
}

Create a new campaign (draft).

Parameters

Name	Type	Required	Description
name	string	Yes	Campaign name
subject	string	Yes	Email subject line
html_body	string	Yes	HTML email body
segment_id	integer	No	Segment ID to target

Example Request

curl -X POST 'https://mediacity.co.in/mailtrixy/public/api/v1/campaigns' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"name":"April Promo","subject":"Special offer inside","html_body":"<h1>Hello!</h1>"}'

Example Response

{
  "data": {"id": 15, "name": "April Promo", "status": "draft"}
}

Send or schedule a campaign. Rate limited to 5 req/min.

Parameters

Name	Type	Required	Description
scheduled_at	datetime	No	ISO 8601 datetime to schedule (omit to send immediately)

Example Request

curl -X POST 'https://mediacity.co.in/mailtrixy/public/api/v1/campaigns/15/send' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json'

Example Response

{
  "data": {"id": 15, "status": "sending"}
}

Workflows

Manage automation workflows. Requires workflows scope.

List all workflows.

Example Request

curl -X GET 'https://mediacity.co.in/mailtrixy/public/api/v1/workflows' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

Example Response

{
  "data": [
    {"id": 1, "name": "Welcome Series", "status": "active", "trigger": "contact.created", "executions_count": 342}
  ]
}

Activate a paused workflow.

Example Request

curl -X POST 'https://mediacity.co.in/mailtrixy/public/api/v1/workflows/1/activate' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Example Response

{"data": {"id": 1, "status": "active"}}

Pause an active workflow.

Example Request

curl -X POST 'https://mediacity.co.in/mailtrixy/public/api/v1/workflows/1/pause' \
  -H 'Authorization: Bearer YOUR_TOKEN'

Example Response

{"data": {"id": 1, "status": "paused"}}

Knowledge Base

Manage KB documents for AI context. Requires knowledge-base scope.

List knowledge base documents.

Parameters

Name	Type	Required	Description
search	string	No	Search document titles
per_page	integer	No	Results per page

Example Request

curl -X GET 'https://mediacity.co.in/mailtrixy/public/api/v1/knowledge-base' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

Example Response

{
  "data": [
    {"id": 1, "title": "Product FAQ", "type": "file", "file_size": 245760, "chunks_count": 24, "created_at": "2026-03-10T12:00:00Z"}
  ]
}

Upload a document to the knowledge base.

Parameters

Name	Type	Required	Description
title	string	Yes	Document title
file	file	Yes	PDF, DOCX, or TXT file

Example Request

curl -X POST 'https://mediacity.co.in/mailtrixy/public/api/v1/knowledge-base' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -F 'title=Return Policy' \
  -F '[email protected]'

Example Response

{
  "data": {"id": 5, "title": "Return Policy", "status": "processing"}
}

Scrape a website URL and add it to the knowledge base. Rate limited to 3 req/min.

Parameters

Name	Type	Required	Description
url	string	Yes	URL to scrape
title	string	No	Custom title (auto-detected if omitted)

Example Request

curl -X POST 'https://mediacity.co.in/mailtrixy/public/api/v1/knowledge-base/scrape' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/help"}'

Example Response

{
  "data": {"id": 6, "title": "Help Center", "type": "url", "status": "processing"}
}

AI

AI-powered features. Requires ai scope. Stricter rate limits apply.

Generate an AI-powered reply for a conversation. Rate limited to 10 req/min.

Parameters

Name	Type	Required	Description
conversation_id	integer	Yes	Conversation to generate a reply for
tone	string	No	Reply tone: professional, friendly, concise
instructions	string	No	Additional context for the AI

Example Request

curl -X POST 'https://mediacity.co.in/mailtrixy/public/api/v1/ai/generate-reply' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"conversation_id":1,"tone":"professional"}'

Example Response

{
  "data": {
    "reply": "Thank you for contacting us regarding your billing inquiry...",
    "tokens_used": 245,
    "model": "gpt-4"
  }
}

Analyze the sentiment of a text or conversation. Rate limited to 20 req/min.

Parameters

Name	Type	Required	Description
text	string	No	Text to analyze (provide this or conversation_id)
conversation_id	integer	No	Conversation ID to analyze

Example Request

curl -X POST 'https://mediacity.co.in/mailtrixy/public/api/v1/ai/analyze-sentiment' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"text":"I am very frustrated with the late delivery"}'

Example Response

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

Analytics

Read-only analytics data. Requires analytics scope.

Get workspace analytics overview.

Parameters

Name	Type	Required	Description
period	string	No	7d, 30d, 90d (default: 30d)

Example Request

curl -X GET 'https://mediacity.co.in/mailtrixy/public/api/v1/analytics/overview?period=30d' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

Example Response

{
  "data": {
    "conversations": {"total": 524, "open": 38, "avg_resolution_hours": 4.2},
    "contacts": {"total": 12500, "new_this_period": 320},
    "campaigns": {"sent": 8, "avg_open_rate": 32.1, "avg_click_rate": 6.8},
    "ai": {"replies_generated": 186, "tokens_used": 45200}
  }
}

Get team performance metrics.

Parameters

Name	Type	Required	Description
period	string	No	7d, 30d, 90d

Example Request

curl -X GET 'https://mediacity.co.in/mailtrixy/public/api/v1/analytics/team' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

Example Response

{
  "data": [
    {"user_id": 2, "name": "Agent Smith", "conversations_handled": 142, "avg_response_minutes": 12, "satisfaction_score": 4.6}
  ]
}

Name	Type	Required	Description
name	string	Yes	Tag name (unique per workspace)
color	string	No	Hex color code (e.g. #8B5CF6)

Canned Responses

Manage saved reply templates. Requires canned-responses scope.

List all canned responses.

Example Request

curl -X GET 'https://mediacity.co.in/mailtrixy/public/api/v1/canned-responses' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

Example Response

{
  "data": [
    {"id": 1, "title": "Greeting", "shortcut": "/greet", "body": "Hello! How can I help you today?"}
  ]
}

Create a new canned response.

Parameters

Name	Type	Required	Description
title	string	Yes	Template title
shortcut	string	No	Slash command shortcut (e.g. /thanks)
body	string	Yes	Response body (HTML supported)

Example Request

curl -X POST 'https://mediacity.co.in/mailtrixy/public/api/v1/canned-responses' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"title":"Thanks","shortcut":"/thanks","body":"Thank you for your patience!"}'

Example Response

{
  "data": {"id": 5, "title": "Thanks", "shortcut": "/thanks", "body": "Thank you for your patience!"}
}

Try It

Test API endpoints directly from this page.

API Token

Endpoint

Request Body (JSON, for POST/PUT)

Response