API Reference

Maildrone provides a comprehensive REST API that allows you to programmatically manage email campaigns, contacts, send emails, and retrieve analytics.

🚀 Quick Start

Authentication

All API requests require an API key in the request header:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     https://api.maildrone.com/v2/campaigns

Getting Your API Key

Log in to Maildrone dashboard
Go to Settings > API Keys
Click "Create New Key"
Select appropriate permissions
Save the key (shown only once)

Base URL

https://api.maildrone.com/v2

Response Format

All responses use JSON format:

// Success response
{
  "success": true,
  "data": {
    // Response data
  },
  "meta": {
    "timestamp": "2024-03-20T10:30:00Z",
    "request_id": "req_1a2b3c4d"
  }
}

// Error response
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request parameters",
    "details": {
      "field": "email",
      "issue": "Invalid email format"
    }
  },
  "meta": {
    "timestamp": "2024-03-20T10:30:00Z",
    "request_id": "req_1a2b3c4d"
  }
}

Status Codes

Code	Description
200	Request successful
201	Resource created
400	Bad request
401	Authentication failed
403	Insufficient permissions
404	Resource not found
429	Rate limit exceeded
500	Internal server error

👥 Contacts

List Contacts

GET /v2/contacts

Query Parameters

Parameter	Type	Description
`page`	integer	Page number, default 1
`limit`	integer	Items per page, default 20, max 100
`search`	string	Search keyword
`tags`	string	Filter by tags, comma-separated
`status`	string	Filter by status: `active`, `unsubscribed`

Example Request

curl -H "Authorization: Bearer YOUR_API_KEY" \
     "https://api.maildrone.com/v2/contacts?page=1&limit=20&tags=vip,active"

Response Example

{
  "success": true,
  "data": [
    {
      "id": "contact_1a2b3c4d",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "+1-555-0123",
      "company": "Tech Company Inc.",
      "tags": ["vip", "active"],
      "custom_fields": {
        "customer_level": "gold",
        "last_purchase": "2024-03-15"
      },
      "status": "active",
      "subscribed_at": "2024-01-15T08:30:00Z",
      "created_at": "2024-01-15T08:30:00Z",
      "updated_at": "2024-03-20T10:15:00Z"
    }
  ],
  "meta": {
    "total": 25324,
    "page": 1,
    "limit": 20,
    "pages": 1267
  }
}

Create Contact

POST /v2/contacts

Request Body

{
  "email": "[email protected]",
  "first_name": "Jane",
  "last_name": "Smith",
  "phone": "+1-555-0124",
  "company": "Startup Co.",
  "tags": ["new", "trial"],
  "custom_fields": {
    "source": "website",
    "interests": ["tech", "marketing"]
  },
  "send_welcome": true
}

Update Contact

PUT /v2/contacts/{contact_id}

Delete Contact

DELETE /v2/contacts/{contact_id}

📧 Campaigns

List Campaigns

GET /v2/campaigns

Create Campaign

POST /v2/campaigns

Request Body

{
  "name": "Summer Sale Campaign",
  "subject": "☀️ Summer Clearance - Up to 70% Off!",
  "from_name": "Maildrone Team",
  "from_email": "[email protected]",
  "reply_to": "[email protected]",
  "content": {
    "html": "<html>...</html>",
    "text": "Plain text version..."
  },
  "recipients": {
    "type": "tags",
    "tags": ["active", "vip"],
    "exclude_tags": ["unengaged"]
  },
  "settings": {
    "track_opens": true,
    "track_clicks": true,
    "google_analytics": true
  },
  "send_time": "2024-03-25T10:00:00Z"
}

Send Campaign

POST /v2/campaigns/{campaign_id}/send

📊 Analytics

Get Campaign Stats

GET /v2/campaigns/{campaign_id}/stats

Response Example

{
  "success": true,
  "data": {
    "campaign_id": "campaign_1a2b3c4d",
    "stats": {
      "sent": 10000,
      "delivered": 9456,
      "bounced": 544,
      "opened": 2367,
      "clicked": 473,
      "unsubscribed": 23,
      "spam_reports": 5
    },
    "rates": {
      "delivery_rate": 0.9456,
      "open_rate": 0.2504,
      "click_rate": 0.0500,
      "unsubscribe_rate": 0.0024
    }
  }
}

🔔 Webhooks

Event Types

email.sent - Email sent successfully
email.delivered - Email delivered
email.opened - Email opened
email.clicked - Link clicked
email.bounced - Email bounced
email.unsubscribed - User unsubscribed

Webhook Signature Verification

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
    
  return signature === `sha256=${expectedSignature}`;
}

📈 Rate Limits

API Type	Limit	Window
Read APIs	1000 requests/hour	Sliding window
Write APIs	300 requests/hour	Sliding window
Email Sending	Based on plan	Monthly

For more detailed API documentation and examples, visit our API Reference or join our Developer Community.

API Reference

On this page