# Mailsoftly — Email Marketing & Automation API

> Mailsoftly is an email marketing and automation platform. Build integrations, manage contacts, send campaigns, and automate workflows via REST API and MCP server.

## Quick Links

- Website: https://mailsoftly.com
- API Documentation: https://app.mailsoftly.com/developers
- MCP Server Documentation: https://app.mailsoftly.com/developers/mcp
- OpenAPI Spec: https://app.mailsoftly.com/developers/openapi.json
- AI Plugin Manifest: https://app.mailsoftly.com/.well-known/ai-plugin.json

## API Overview

- Base URL: `https://app.mailsoftly.com/api/v3/`
- Auth: API token in `Authorization` header (raw token, no "Bearer" prefix)
- Format: JSON
- Rate Limit: 300 requests per 5 minutes per IP

## Live Endpoints (23)

### Authentication
- `POST /api/v3/authentication` — Verify API credentials

### Contacts
- `GET /api/v3/get_contacts` — List all contacts
- `GET /api/v3/get_contact?contact_id=ID` — Get one contact (add `type=detailed` for all fields)
- `GET /api/v3/get_contact_fields` — List available contact fields
- `POST /api/v3/create_contact` — Create a contact (email required)
- `POST /api/v3/update_contact` — Update a contact
- `POST /api/v3/create_or_update_contact` — Create or update
- `GET /api/v3/search_contacts` — Search by email, first_name, last_name

### Contact Lists
- `GET /api/v3/get_contact_lists` — List all contact lists
- `GET /api/v3/get_contact_list?contact_list_id=ID` — Get one list
- `GET /api/v3/get_contact_list_contacts?contact_list_id=ID` — List contacts in a list
- `POST /api/v3/create_contact_list` — Create a list
- `POST /api/v3/add_contact_to_contact_list` — Add contact to list
- `POST /api/v3/add_contacts_to_contact_list` — Bulk add contacts

### Tags
- `GET /api/v3/get_tags` — List all tags
- `POST /api/v3/assign_tag_to_contact` — Assign tag
- `POST /api/v3/assign_tags_to_contact` — Assign multiple tags

### Custom Fields
- `GET /api/v3/get_custom_fields` — List custom fields
- `POST /api/v3/add_custom_field_to_contact` — Set custom field on contact

### Emails
- `POST /api/v3/create_emails` — Create email drafts
- `GET /api/v3/email_status?id=ID` — Check draft status
- `POST /api/v3/send_email` — Send a draft

### Unsubscribes
- `POST /api/v3/add_global_email_unsubscriber` — Unsubscribe email
- `POST /api/v3/remove_global_email_unsubscriber` — Resubscribe email
- `POST /api/v3/add_global_sms_unsubscriber` — Unsubscribe from SMS
- `POST /api/v3/remove_global_sms_unsubscriber` — Resubscribe to SMS

## Coming Soon Endpoints (20)
- Email Templates, Email Senders, Automations, Forms, Form Responses
- Landing Pages, SMS Campaigns, Segments, Integrations, Webhooks
- Signatures, Suppressions, Account Info, Team Members

## AI Integration

### MCP Server (Claude Desktop, Cursor, VS Code, Claude Code)
Mailsoftly provides a Model Context Protocol (MCP) server for AI-powered email marketing.

```json
{
  "mcpServers": {
    "mailsoftly": {
      "command": "node",
      "args": ["/path/to/mcp-server/build/index.js"],
      "env": {
        "API_KEY_API_KEY": "your-api-key",
        "API_BASE_URL": "https://app.mailsoftly.com"
      }
    }
  }
}
```

### OpenAI / ChatGPT (GPT Actions)
Use the OpenAPI spec directly in GPT Actions:
- Spec URL: `https://app.mailsoftly.com/developers/openapi.json`
- Auth: API Key in `Authorization` header (custom header, no prefix)
- Plugin manifest: `https://app.mailsoftly.com/.well-known/ai-plugin.json`

### Google Gemini / Vertex AI
Import the OpenAPI spec as a Vertex AI Extension:
- Spec URL: `https://app.mailsoftly.com/developers/openapi.json`
- Auth type: API Key header

### xAI / Grok
Use the OpenAPI spec for function calling:
- Spec URL: `https://app.mailsoftly.com/developers/openapi.json`
- Tools can be generated from the spec for Grok's tool-use capability

### GitHub Copilot
The OpenAPI spec and `llms.txt` enable Copilot to understand and generate Mailsoftly API calls.

### Perplexity / AI Search Engines
This `llms.txt` file and the structured data on `/developers` and `/developers/mcp` pages enable AI search engines to discover and describe Mailsoftly's API capabilities.

## Error Format
```json
{ "status": "error", "error": "description" }
```
- 401: Invalid/missing token
- 404: Resource not found
- 422: Validation error
- 429: Rate limit exceeded

## About Mailsoftly
Mailsoftly is an email marketing and automation platform used by 35,000+ businesses. Features include email campaigns, automations & drip sequences, SMS marketing, AI agent, embeddable forms, landing pages, contact management, segmentation, and multi-user team support. Free plan available at https://mailsoftly.com