How-To Guide

This guide will walk you through the process of using the MergeDesk API to create and send personalized email campaigns. Follow these steps to get started quickly.

Prerequisites

• A MergeDesk account
• An email template (created in the MergeDesk interface)
• A CSV file with recipient data
• Basic knowledge of HTTP requests and JSON

Step 1: Generate an API Key

Generate a New API Key

1. Click the Generate New Key button
2. Enter a descriptive name for your key (e.g., "Production Server", "Development", "My Python Script")
3. Select the required scopes:
   • templates:read - To view available templates
   • campaigns:create - To create new campaigns
   • campaigns:read - To check campaign status
   • campaigns:send - To send campaigns
4. Click Create API Key

Save Your API Key

Your API key will look like this:

md_live_01e455df873a8506ed879459125dc2e6

Step 2: Prepare Your Email Template

Create or Select an Email Template

Before creating a campaign, you need an email template. Navigate to Email Templates and either create a new template or note the ID of an existing one.

Template Merge Fields

Templates support merge fields using double curly braces. For example:

Hello {{name}},

Thank you for joining {{company}}!

Your order number is {{order_id}}.

Step 3: Prepare Your CSV File

Create a CSV File

Your CSV file must include an email column. Additional columns can be used as merge fields in your template.

Example CSV:

email,name,company,order_id
john@example.com,John Smith,Acme Corp,12345
jane@example.com,Jane Doe,Tech Inc,12346
bob@example.com,Bob Johnson,StartupXYZ,12347

Step 4: Make Your First API Request

Get Available Templates

First, let's retrieve your available email templates to get the template ID:

curl -X GET https://mergedesk.send-it.network/api/v1/templates/email \
  -H "Authorization: Bearer md_live_YOUR_API_KEY"

Response:

{
  "success": true,
  "data": {
    "templates": [
      {
        "id": 11,
        "name": "Promotion Email",
        "subject": "Special Offer!",
        ...
      }
    ]
  }
}

Note the id value (in this case, 11) for the template you want to use.

Create a Campaign

Now create a campaign by uploading your CSV file:

curl -X POST https://mergedesk.send-it.network/api/v1/campaigns \
  -H "Authorization: Bearer md_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Holiday Promotion",
    "subject": "Special Holiday Offer for {{name}}",
    "email_template_id": 11,
    "csv_data": [
      {
        "email": "john@example.com",
        "name": "John Smith",
        "company": "Acme Corp"
      },
      {
        "email": "jane@example.com",
        "name": "Jane Doe",
        "company": "Tech Inc"
      }
    ],
    "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 the Campaign

Once your campaign is created, send it to all recipients:

curl -X POST https://mergedesk.send-it.network/api/v1/campaigns/123/send \
  -H "Authorization: Bearer md_live_YOUR_API_KEY"

Response:

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

Check Campaign Status

Monitor your campaign's progress:

curl -X GET https://mergedesk.send-it.network/api/v1/campaigns/123 \
  -H "Authorization: Bearer md_live_YOUR_API_KEY"

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"
  }
}

Advanced Examples

Python Example

import requests
import json

# Configuration
API_KEY = "md_live_YOUR_API_KEY"
BASE_URL = "https://mergedesk.send-it.network/api/v1"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Get templates
response = requests.get(f"{BASE_URL}/templates/email", headers=headers)
templates = response.json()["data"]["templates"]
template_id = templates[0]["id"]

# Create campaign
campaign_data = {
    "name": "Python API Campaign",
    "subject": "Hello {{name}} from Python!",
    "email_template_id": template_id,
    "csv_data": [
        {"email": "test@example.com", "name": "Test User"}
    ],
    "from_name": "Python Script",
    "from_email": "noreply@example.com"
}

response = requests.post(
    f"{BASE_URL}/campaigns",
    headers=headers,
    data=json.dumps(campaign_data)
)

campaign = response.json()["data"]
campaign_id = campaign["campaign_id"]

# Send campaign
response = requests.post(
    f"{BASE_URL}/campaigns/{campaign_id}/send",
    headers=headers
)

print(f"Campaign {campaign_id} sent successfully!")

JavaScript/Node.js Example

const fetch = require('node-fetch');

const API_KEY = 'md_live_YOUR_API_KEY';
const BASE_URL = 'https://mergedesk.send-it.network/api/v1';

const headers = {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
};

async function createAndSendCampaign() {
    try {
        // Get templates
        const templatesResponse = await fetch(`${BASE_URL}/templates/email`, { headers });
        const templatesData = await templatesResponse.json();
        const templateId = templatesData.data.templates[0].id;

        // Create campaign
        const campaignData = {
            name: 'JavaScript API Campaign',
            subject: 'Hello {{name}} from JavaScript!',
            email_template_id: templateId,
            csv_data: [
                { email: 'test@example.com', name: 'Test User' }
            ],
            from_name: 'JavaScript Script',
            from_email: 'noreply@example.com'
        };

        const campaignResponse = await fetch(`${BASE_URL}/campaigns`, {
            method: 'POST',
            headers,
            body: JSON.stringify(campaignData)
        });

        const campaign = await campaignResponse.json();
        const campaignId = campaign.data.campaign_id;

        // Send campaign
        await fetch(`${BASE_URL}/campaigns/${campaignId}/send`, {
            method: 'POST',
            headers
        });

        console.log(`Campaign ${campaignId} sent successfully!`);
    } catch (error) {
        console.error('Error:', error);
    }
}

createAndSendCampaign();

Best Practices

Security

• Never commit API keys to version control
• Use environment variables to store API keys
• Rotate API keys regularly
• Use the minimum required scopes for your application

Performance

• Monitor rate limits and implement backoff strategies
• Use batch operations when possible
• Cache template data to reduce API calls
• Implement proper error handling and retries

Testing

• Always test with a small recipient list first
• Verify your templates render correctly
• Check that merge fields are populated properly
• Monitor campaign status and handle failures

Troubleshooting

Common Issues

Authentication Errors

Problem: Getting 401 Unauthorized errors

Solution: Verify your API key is correct and has the required scopes

Template Not Found

Problem: Template ID doesn't exist

Solution: Use the templates endpoint to get valid template IDs

CSV Validation Errors

Problem: Campaign creation fails with validation errors

Solution: Ensure your CSV has an 'email' column and matches template merge fields

Rate Limiting

Problem: Getting 429 Too Many Requests

Solution: Implement exponential backoff and respect rate limits