MailerX

Developer Documentation

Comprehensive API reference and developer resources for integrating with MailerX.

Introduction to MailerX API

The MailerX API is a RESTful API that allows you to programmatically access and manage your email marketing campaigns, subscribers, and analytics data.

Base URL

All API requests should be made to the following base URL:

json
https://api.mailerx.com/v1

API Versioning

The MailerX API uses versioning to ensure backward compatibility. The current version is v1. We recommend specifying the API version in the URL to ensure your integrations continue to work as expected when we release new versions.

json
https://api.mailerx.com/v1/subscribers

Request Format

The API accepts JSON-encoded request bodies and returns JSON-encoded responses. You should include the Content-Type: application/json header in all requests that include a request body.

json
curl -X POST https://api.mailerx.com/v1/subscribers \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe"
  }'

Next Steps

Authentication

All API requests must be authenticated using an API key. You can generate an API key in your MailerX dashboard under Settings > API.

API Keys

Your API key carries many privileges, so be sure to keep it secure. Do not share your API key in publicly accessible areas such as GitHub, client-side code, or in your frontend application.

json
Authorization: Bearer YOUR_API_KEY

Authentication Example

Here's an example of how to authenticate your API requests:

bash
curl -X GET https://api.mailerx.com/v1/subscribers \
  -H "Authorization: Bearer YOUR_API_KEY"

Never expose your API key in client-side JavaScript. Always make API requests from your server to protect your API key.

Next Steps

Rate Limits

To ensure the stability of the API, we enforce rate limits on the number of requests you can make within a specific time period.

Current Limits

The current rate limits are:

Parameters

NameTypeRequiredDescription
Free Plan100YesRequests per minute
Pro Plan500YesRequests per minute
Enterprise Plan2000YesRequests per minute

Rate Limit Headers

Each API response includes headers that provide information about your current rate limit status:

Parameters

NameTypeRequiredDescription
X-RateLimit-LimitintegerYesThe maximum number of requests allowed per minute
X-RateLimit-RemainingintegerYesThe number of requests remaining in the current rate limit window
X-RateLimit-ResettimestampYesThe time at which the current rate limit window resets in UTC epoch seconds

Exceeding Rate Limits

If you exceed the rate limit, you will receive a 429 Too Many Requests response with a Retry-After header indicating how long to wait before making another request.

Response

Response
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please try again in 30 seconds."
  }
}

Next Steps

Error Handling

The MailerX API uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

Here are the HTTP status codes you might encounter:

Parameters

NameTypeRequiredDescription
200 - OKSuccessNoThe request was successful
201 - CreatedSuccessNoThe resource was successfully created
400 - Bad RequestErrorNoThe request was invalid or cannot be otherwise served
401 - UnauthorizedErrorNoAuthentication credentials were missing or incorrect
403 - ForbiddenErrorNoThe request is understood, but it has been refused or access is not allowed
404 - Not FoundErrorNoThe requested resource could not be found
429 - Too Many RequestsErrorNoYou have exceeded the rate limit
500, 502, 503, 504 - Server ErrorsErrorNoSomething went wrong on our end

Error Response Format

Error responses include a JSON object with an error code and message:

Response

Response
{
  "error": {
    "code": "invalid_request",
    "message": "The email address is invalid."
  }
}

Common Error Codes

Parameters

NameTypeRequiredDescription
invalid_requeststringNoThe request was invalid
authentication_failedstringNoAuthentication failed
permission_deniedstringNoYou don't have permission to access this resource
resource_not_foundstringNoThe requested resource could not be found
rate_limit_exceededstringNoYou have exceeded the rate limit

Next Steps

Campaigns API

The Campaigns API allows you to create, manage, and send email campaigns programmatically.

List Campaigns

Retrieve a list of all your campaigns:

json
GET /campaigns

Response

Response
{
  "data": [
    {
      "id": "camp_123456",
      "name": "Monthly Newsletter",
      "subject": "May Updates",
      "status": "draft",
      "created_at": "2023-05-01T12:00:00Z",
      "scheduled_for": null
    },
    {
      "id": "camp_789012",
      "name": "Product Launch",
      "subject": "Introducing Our New Feature",
      "status": "sent",
      "created_at": "2023-04-15T10:30:00Z",
      "scheduled_for": "2023-04-20T09:00:00Z"
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "per_page": 10
  }
}

Create Campaign

Create a new email campaign:

json
POST /campaigns

{
  "name": "Summer Sale",
  "subject": "Don't Miss Our Summer Sale!",
  "from_name": "MailerX Team",
  "from_email": "marketing@example.com",
  "content": {
    "html": "<html><body><h1>Summer Sale</h1><p>Save up to 50% on all products!</p></body></html>",
    "plain": "Summer Sale\n\nSave up to 50% on all products!"
  },
  "list_id": "list_123456"
}

Response

Response
{
  "data": {
    "id": "camp_345678",
    "name": "Summer Sale",
    "subject": "Don't Miss Our Summer Sale!",
    "status": "draft",
    "created_at": "2023-05-10T14:22:00Z",
    "scheduled_for": null
  }
}

Get Campaign

Retrieve a specific campaign by ID:

json
GET /campaigns/{campaign_id}

Response

Response
{
  "data": {
    "id": "camp_345678",
    "name": "Summer Sale",
    "subject": "Don't Miss Our Summer Sale!",
    "from_name": "MailerX Team",
    "from_email": "marketing@example.com",
    "content": {
      "html": "<html><body><h1>Summer Sale</h1><p>Save up to 50% on all products!</p></body></html>",
      "plain": "Summer Sale\n\nSave up to 50% on all products!"
    },
    "list_id": "list_123456",
    "status": "draft",
    "created_at": "2023-05-10T14:22:00Z",
    "scheduled_for": null,
    "sent_at": null,
    "stats": {
      "recipients": 0,
      "opens": 0,
      "clicks": 0,
      "unsubscribes": 0,
      "bounces": 0
    }
  }
}

Send Campaign

Send a campaign immediately or schedule it for later:

json
POST /campaigns/{campaign_id}/send

{
  "schedule": "2023-06-01T09:00:00Z"
}

Response

Response
{
  "data": {
    "id": "camp_345678",
    "status": "scheduled",
    "scheduled_for": "2023-06-01T09:00:00Z"
  }
}

Next Steps

Subscribers API

The Subscribers API allows you to manage your email subscribers, including adding, updating, and removing subscribers from your lists.

List Subscribers

Retrieve a list of all your subscribers:

json
GET /subscribers

Response

Response
{
  "data": [
    {
      "id": "sub_123456",
      "email": "john@example.com",
      "first_name": "John",
      "last_name": "Doe",
      "status": "subscribed",
      "created_at": "2023-04-10T08:15:00Z",
      "custom_fields": {
        "company": "Acme Inc",
        "plan": "Pro"
      }
    },
    {
      "id": "sub_789012",
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Smith",
      "status": "subscribed",
      "created_at": "2023-04-12T14:30:00Z",
      "custom_fields": {
        "company": "XYZ Corp",
        "plan": "Basic"
      }
    }
  ],
  "meta": {
    "total": 2,
    "page": 1,
    "per_page": 10
  }
}

Create Subscriber

Add a new subscriber:

json
POST /subscribers

{
  "email": "user@example.com",
  "first_name": "Alex",
  "last_name": "Johnson",
  "status": "subscribed",
  "custom_fields": {
    "company": "Tech Solutions",
    "plan": "Enterprise"
  },
  "list_ids": ["list_123456", "list_789012"]
}

Response

Response
{
  "data": {
    "id": "sub_345678",
    "email": "user@example.com",
    "first_name": "Alex",
    "last_name": "Johnson",
    "status": "subscribed",
    "created_at": "2023-05-10T15:45:00Z",
    "custom_fields": {
      "company": "Tech Solutions",
      "plan": "Enterprise"
    }
  }
}

Get Subscriber

Retrieve a specific subscriber by ID:

json
GET /subscribers/{subscriber_id}

Response

Response
{
  "data": {
    "id": "sub_345678",
    "email": "user@example.com",
    "first_name": "Alex",
    "last_name": "Johnson",
    "status": "subscribed",
    "created_at": "2023-05-10T15:45:00Z",
    "custom_fields": {
      "company": "Tech Solutions",
      "plan": "Enterprise"
    },
    "lists": [
      {
        "id": "list_123456",
        "name": "Newsletter Subscribers"
      },
      {
        "id": "list_789012",
        "name": "Product Updates"
      }
    ],
    "activity": {
      "campaigns_received": 5,
      "last_open": "2023-05-15T10:20:00Z",
      "last_click": "2023-05-15T10:22:00Z"
    }
  }
}

Update Subscriber

Update an existing subscriber:

json
PATCH /subscribers/{subscriber_id}

{
  "first_name": "Alexander",
  "custom_fields": {
    "plan": "Premium"
  }
}

Response

Response
{
  "data": {
    "id": "sub_345678",
    "email": "user@example.com",
    "first_name": "Alexander",
    "last_name": "Johnson",
    "status": "subscribed",
    "created_at": "2023-05-10T15:45:00Z",
    "custom_fields": {
      "company": "Tech Solutions",
      "plan": "Premium"
    }
  }
}

Delete Subscriber

Remove a subscriber:

json
DELETE /subscribers/{subscriber_id}

Response

Response
{
  "data": {
    "deleted": true
  }
}

Next Steps

JavaScript SDK

The MailerX JavaScript SDK provides a convenient way to interact with the MailerX API from your JavaScript applications.

Installation

Install the SDK using npm or yarn:

bash
# Using npm
npm install mailerx-js

# Using yarn
yarn add mailerx-js

Initialization

Initialize the SDK with your API key:

javascript
import MailerX from 'mailerx-js';

const mailerx = new MailerX('YOUR_API_KEY');

Examples

Here are some examples of how to use the SDK:

javascript
// List all subscribers
const subscribers = await mailerx.subscribers.list();

// Create a new subscriber
const newSubscriber = await mailerx.subscribers.create({
  email: 'user@example.com',
  first_name: 'John',
  last_name: 'Doe',
  list_ids: ['list_123456']
});

// Send a campaign
const campaign = await mailerx.campaigns.send('camp_123456', {
  schedule: '2023-06-01T09:00:00Z'
});

Error Handling

The SDK throws errors for API failures that you can catch and handle:

javascript
try {
  const subscriber = await mailerx.subscribers.get('invalid_id');
} catch (error) {
  console.error('Error fetching subscriber:', error.message);
  // Error fetching subscriber: Resource not found
}

Next Steps

Ready to start building?

Create a free account to get your API key and start integrating with MailerX today.

Sign up for free View on GitHub