API Documentation

The MergeDesk API allows you to programmatically create and send email campaigns with CSV data and PDF attachments. All API requests require authentication via API keys.

Getting Started

Quick Start

1. Log in to your MergeDesk account
2. Navigate to Settings → API Keys
3. Generate a new API key with required scopes
4. Use the API key in your requests via the Authorization header

Authentication

All API requests must include an API key in the Authorization header using Bearer token format.

API Key Format

Authorization: Bearer md_live_YOUR_API_KEY_HERE

API Key Scopes

API keys support granular permissions. Available scopes:

• templates:read - View email and PDF templates
• campaigns:create - Create new campaigns
• campaigns:read - View campaign status and details
• campaigns:send - Send campaigns to recipients

Rate Limits

API requests are rate-limited to ensure system stability:

• Per Minute: 100 requests
• Per Hour: 1,000 requests
• Per Day: 10,000 requests

Rate limit information is returned in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000
Retry-After: 60

API Endpoints

Get Email Templates

GET /api/v1/templates/email

Retrieve all available email templates for your account.

Required Scope

templates:read

Response

{
  "success": true,
  "data": {
    "templates": [
      {
        "id": 11,
        "name": "Promotion Email",
        "subject": "Special Offer Inside!",
        "body": "Hello {{name}}, check out our offer...",
        "user_id": 5,
        "is_global": false,
        "created_at": "2025-10-06 08:00:00"
      }
    ]
  }
}

Get PDF Templates

GET /api/v1/templates/pdf

Retrieve all available PDF templates for your account.

Required Scope

templates:read

Response

{
  "success": true,
  "data": {
    "templates": [
      {
        "id": 5,
        "name": "Invoice Template",
        "page_format": "A4",
        "orientation": "P",
        "user_id": 5,
        "is_global": false,
        "created_at": "2025-10-06 08:00:00"
      }
    ]
  }
}

Create Campaign

POST /api/v1/campaigns

Create a new email campaign with CSV data and optional PDF attachments.

Required Scopes

campaigns:create, templates:read

Request Body

{
  "name": "Holiday Promotion",
  "subject": "Special Holiday Offer for {{name}}",
  "email_template_id": 11,
  "pdf_template_id": 5,
  "csv_data": [
    {
      "email": "john@example.com",
      "name": "John Doe",
      "company": "Acme Corp"
    },
    {
      "email": "jane@example.com", 
      "name": "Jane Smith",
      "company": "Tech Solutions"
    }
  ],
  "from_name": "Your Company",
  "from_email": "noreply@yourcompany.com"
}

Response

{
  "success": true,
  "data": {
    "campaign_id": 123,
    "status": "draft",
    "recipient_count": 2,
    "message": "Campaign created successfully"
  }
}

Send Campaign

POST /api/v1/campaigns/{id}/send

Send a campaign to all recipients. The campaign must be in 'draft' or 'ready' status.

Required Scopes

campaigns:send, campaigns:read

Response

{
  "success": true,
  "data": {
    "campaign_id": 123,
    "status": "sending",
    "message": "Campaign started successfully"
  }
}

Get Campaign Status

GET /api/v1/campaigns/{id}

Retrieve campaign details and current status.

Required Scope

campaigns:read

Response

{
  "success": true,
  "data": {
    "id": 123,
    "name": "Holiday Promotion",
    "status": "completed",
    "recipient_count": 2,
    "sent_count": 2,
    "failed_count": 0,
    "created_at": "2025-10-06 08:00:00",
    "started_at": "2025-10-06 08:05:00",
    "completed_at": "2025-10-06 08:07:00"
  }
}

Get Campaign Progress

GET /api/v1/campaigns/{id}/progress

Get real-time progress information for a sending campaign.

Required Scope

campaigns:read

Response

{
  "success": true,
  "data": {
    "campaign_id": 123,
    "status": "sending",
    "progress": {
      "total": 1000,
      "sent": 750,
      "failed": 5,
      "remaining": 245,
      "percentage": 75.5
    },
    "estimated_completion": "2025-10-06T08:15:00Z"
  }
}

Error Responses

All API endpoints return consistent error responses:

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired"
  }
}

Common Error Codes

Code	Description	HTTP Status
INVALID_API_KEY	API key is missing, invalid, or expired	401
INSUFFICIENT_SCOPE	API key lacks required permissions	403
RATE_LIMIT_EXCEEDED	Too many requests in the time period	429
VALIDATION_ERROR	Request data validation failed	400
RESOURCE_NOT_FOUND	Requested resource does not exist	404
INTERNAL_ERROR	Server-side error occurred	500

SDKs and Libraries

While MergeDesk provides a RESTful API that can be used with any HTTP client, we recommend using these libraries for popular programming languages:

• JavaScript/Node.js: Use fetch or axios for HTTP requests
• Python: Use requests library
• PHP: Use cURL or Guzzle
• cURL: Direct command-line usage

Example: JavaScript

const response = await fetch('https://mergedesk.send-it.network/api/v1/templates/email', {
  headers: {
    'Authorization': 'Bearer md_live_YOUR_API_KEY_HERE',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

Example: Python

import requests

headers = {
    'Authorization': 'Bearer md_live_YOUR_API_KEY_HERE',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://mergedesk.send-it.network/api/v1/templates/email',
    headers=headers
)

data = response.json()
print(data)

Example: cURL

curl -X GET \
  'https://mergedesk.send-it.network/api/v1/templates/email' \
  -H 'Authorization: Bearer md_live_YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json'