NAV

Mailblast API Docs

cURL PHP Ruby

Introduction

Welcome to the Mailblast REST API! You can use our API to access resources within your Mailblast account.

You need an Auth Token which is available from your Mailblast account at https://mailblast.io/account/api_access.

The Auth Token, along with your Account Email are required to authenticate against the API.

Lists

Get All Lists

This endpoint retrieves all Lists.

curl -H "X-USER-TOKEN: [USER_TOKEN]" \
     -H "X-USER-EMAIL: [USER_EMAIL]" \
     https://api.mailblast.io/v1/lists

<?php
  $url = 'https://api.mailblast.io/v1/lists';
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'X-USER-TOKEN: [USER_TOKEN]',
    'X-USER-EMAIL: [USER_EMAIL]'
  ));

  curl_exec($ch);
  curl_close($ch);
?>

require 'faraday'
require 'faraday_middleware'

connection = Faraday.new(url: 'https://api.mailblast.io') do |f|
  f.headers['X-USER-TOKEN'] = '[YOUR_AUTH_TOKEN]'
  f.headers['X-USER-EMAIL'] = '[YOUR_EMAIL_ADDRESS]'
  f.request :json
  f.response :json
  f.adapter Faraday.default_adapter
end
connection.get('/v1/lists')

The above command returns the following JSON response:

{
  "data": [
    {
      "id": "[ID]",
      "type": "lists",
      "attributes": {
        "name": "List 1",
        "active_count": 0,
        "created_at": "2017-01-01T00:00:00Z"
      },
      "links": {
        "self": "https://api.mailblast.io/v1/lists/[ID]"
      }
    }
  ],
  "links": {
    "self": "https://api.mailblast.io/v1/lists?page[number]=1&page[size]=15",
    "next": "https://api.mailblast.io/v1/lists?page[number]=2&page[size]=15",
    "last": "https://api.mailblast.io/v1/lists?page[number]=42&page[size]=15"
  }
}

HTTP Status 200

HTTP Request

GET https://api.mailblast.io/v1/lists

Request Parameters

Parameter Description Default
page[number] Returns the respective page 1
page[size] Items per page (max 100) 15

Get a specific List

This endpoint retrieves a specific List.

curl -H "X-USER-TOKEN: [USER_TOKEN]" \
     -H "X-USER-EMAIL: [USER_EMAIL]" \
     https://api.mailblast.io/v1/lists/[ID]

<?php
  $url = 'https://api.mailblast.io/v1/lists/[ID]';
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'X-USER-TOKEN: [USER_TOKEN]',
    'X-USER-EMAIL: [USER_EMAIL]'
  ));

  curl_exec($ch);
  curl_close($ch);
?>

require 'faraday'
require 'faraday_middleware'

connection = Faraday.new(url: 'https://api.mailblast.io') do |f|
  f.headers['X-USER-TOKEN'] = '[YOUR_AUTH_TOKEN]'
  f.headers['X-USER-EMAIL'] = '[YOUR_EMAIL_ADDRESS]'
  f.request :json
  f.response :json
  f.adapter Faraday.default_adapter
end
connection.get('/v1/lists/[ID]')

The above command returns the following JSON response:

{
  "id": "[ID]",
  "type": "lists",
  "data": {
    "attributes": {
      "name": "List 1",
      "active_count": 0,
      "created_at": "2017-01-01T00:00:00Z"
    },
    "links": {
      "self": "https://api.mailblast.io/v1/lists/[ID]"
    }
  }
}

HTTP Status 200

HTTP Request

GET https://api.mailblast.io/v1/lists/[ID]

Request Parameters

Parameter Description
id The ID of the List to retrieve

Create List

curl -X POST -H "Content-type: application/json" \
     -H "X-USER-TOKEN: [USER TOKEN]" \
     -H "X-USER-EMAIL: [USER EMAIL]" \
     -d '{"data": {"attributes": {"name": "List 1"}}}' \
     https://api.mailblast.io/v1/lists

<?php
  $url = 'https://api.mailblast.io/v1/lists';
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'X-USER-TOKEN: [YOUR_AUTH_TOKEN]',
    'X-USER-EMAIL: [YOUR_EMAIL_ADDRESS]'
  ));

  $params = array('data' => array('attributes' => array(
    'name' => 'List 1'
  )));
  $params_string = json_encode($params);

  curl_setopt($ch, CURLOPT_POSTFIELDS, $params_string);

  curl_exec($ch);
  curl_close($ch);
?>

require 'faraday'
require 'faraday_middleware'

connection = Faraday.new(url: 'https://api.mailblast.io') do |f|
  f.headers['X-USER-TOKEN'] = '[YOUR_AUTH_TOKEN]'
  f.headers['X-USER-EMAIL'] = '[YOUR_EMAIL_ADDRESS]'
  f.request :json
  f.response :json
  f.adapter Faraday.default_adapter
end
connection.post('/v1/lists', {data: {attributes: {name: 'List 1'}}})

The above command returns the following JSON response:

{
  "data": {
    "id": "[ID]",
    "type": "lists",
    "attributes": {
      "name": "List 1",
      "active_count": 0,
      "created_at": "2017-01-01T00:00:00Z"
    },
    "links": {
      "self": "https://api.mailblast.io/v1/lists/[ID]"
    }
  }
}

HTTP Status 201

This endpoint creates a new List.

HTTP Request

POST https://api.mailblast.io/v1/lists

Request Parameters

Parameter Description
name Name of the List

Update List

curl -X PATCH -H "Content-type: application/json" \
  -H "X-USER-TOKEN: [USER_TOKEN]" \
  -H "X-USER-EMAIL: [USER_EMAIL]" \
  -d '{"data": {"attributes": {"name": "List 1 Update"}}}' \
  https://api.mailblast.io/v1/lists/[ID]

<?php
  $url = 'https://api.mailblast.io/v1/lists';
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'X-USER-TOKEN: [YOUR_AUTH_TOKEN]',
    'X-USER-EMAIL: [YOUR_EMAIL_ADDRESS]'
  ));

  $params = array('data' => array('attributes' => array(
    'name' => 'List 1'
  )));
  $params_string = json_encode($params);

  curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PATCH');
  curl_setopt($ch, CURLOPT_POSTFIELDS, $params_string);

  curl_exec($ch);
  curl_close($ch);
?>

require 'faraday'
require 'faraday_middleware'

connection = Faraday.new(url: 'https://api.mailblast.io') do |f|
  f.headers['X-USER-TOKEN'] = '[YOUR_AUTH_TOKEN]'
  f.headers['X-USER-EMAIL'] = '[YOUR_EMAIL_ADDRESS]'
  f.request :json
  f.response :json
  f.adapter Faraday.default_adapter
end
connection.patch('/v1/lists/[ID]', {data: {attributes: {
  name: 'List 1'
}}})

The above command returns the following JSON response:

{
  "data": {
    "id": "[ID]",
    "type": "lists",
    "attributes": {
      "name": "List 1 Update",
      "active_count": 0,
      "created_at": "2017-01-01T00:00:00Z"
    },
    "links": {
      "self": "https://api.mailblast.io/v1/lists/[ID]"
    }
  }
}

HTTP Status 200

This endpoint updates a specific List.

HTTP Request

PATCH https://api.mailblast.io/v1/lists/[ID]

Request Parameters

Parameter Description
id The ID of the List to update
name Name of List

Delete List

curl -X DELETE \
  -H "X-USER-TOKEN: [USER TOKEN]" \
  -H "X-USER-EMAIL: [USER EMAIL]" \
  https://api.mailblast.io/v1/lists/[ID]

<?php
  $url = 'https://api.mailblast.io/v1/lists/[ID]';
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'X-USER-TOKEN: [YOUR_AUTH_TOKEN]',
    'X-USER-EMAIL: [YOUR_EMAIL_ADDRESS]'
  ));

  curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'DELETE');

  curl_exec($ch);
  curl_close($ch);
?>

require 'faraday'
require 'faraday_middleware'

connection = Faraday.new(url: 'https://api.mailblast.io') do |f|
  f.headers['X-USER-TOKEN'] = '[YOUR_AUTH_TOKEN]'
  f.headers['X-USER-EMAIL'] = '[YOUR_EMAIL_ADDRESS]'
  f.request :json
  f.response :json
  f.adapter Faraday.default_adapter
end
connection.delete('/v1/lists/[ID]')

The above command returns the following JSON response:

{}

HTTP Status 204

This endpoint deletes a specific List.

HTTP Request

DELETE https://api.mailblast.io/v1/lists/[ID]

Request Parameters

Parameter Description
id The ID of the List to delete

Subscribers

Get All Subscribers

This endpoint retrieves all Subscribers for a list.

curl \
  -H "X-USER-TOKEN: [USER_TOKEN]" \
  -H "X-USER-EMAIL: [USER_EMAIL]" \
  https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers

<?php
  $url = 'https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers';
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'X-USER-TOKEN: [USER_TOKEN]',
    'X-USER-EMAIL: [USER_EMAIL]'
  ));

  curl_exec($ch);
  curl_close($ch);
?>

require 'faraday'
require 'faraday_middleware'

connection = Faraday.new(url: 'https://api.mailblast.io') do |f|
  f.headers['X-USER-TOKEN'] = '[YOUR_AUTH_TOKEN]'
  f.headers['X-USER-EMAIL'] = '[YOUR_EMAIL_ADDRESS]'
  f.request :json
  f.response :json
  f.adapter Faraday.default_adapter
end
connection.get('/v1/lists/[ID]/subscribers')

The above command returns the following JSON response:

{
  "data": [
    {
      "id": "[ID]",
      "type": "subscribers",
      "attributes": {
        "email": "johnsmith@example.com",
        "first_name": "John",
        "last_name": "Smith",
        "state": "active",
        "created_at": "2017-01-01T00:00:00Z"
      },
      "links": {
        "self": "https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers"
      }
    }
  ],
  "links": {
    "self": "https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers?page[number]=1&page[size]=15",
    "next": "https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers?page[number]=2&page[size]=15",
    "last": "https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers?page[number]=42&page[size]=15"
  }
}

HTTP Status 200

HTTP Request

GET https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers

Request Parameters

Parameter Description Default
page[number] Returns the respective page 1
page[size] Items per page (max 100) 15

Get a specific Subscriber

This endpoint retrieves a specific subscriber.

curl \
  -H "X-USER-TOKEN: [USER_TOKEN]" \
  -H "X-USER-EMAIL: [USER_EMAIL]" \
  https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers/[ID]

<?php
  $url = 'https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers/[ID';
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'X-USER-TOKEN: [USER_TOKEN]',
    'X-USER-EMAIL: [USER_EMAIL]'
  ));

  curl_exec($ch);
  curl_close($ch);
?>

require 'faraday'
require 'faraday_middleware'

connection = Faraday.new(url: 'https://api.mailblast.io') do |f|
  f.headers['X-USER-TOKEN'] = '[YOUR_AUTH_TOKEN]'
  f.headers['X-USER-EMAIL'] = '[YOUR_EMAIL_ADDRESS]'
  f.request :json
  f.response :json
  f.adapter Faraday.default_adapter
end
connection.get('/v1/lists/[LIST_ID]/subscribers/[ID]')

The above command returns the following JSON response:

{
  "data": {
    "id": "[ID]",
    "type": "subscribers",
    "attributes": {
      "email": "johnsmith@example.com",
      "first_name": "John",
      "last_name": "Smith",
      "state": "active",
      "created_at": "2017-01-01T00:00:00Z"
    },
    "links": {
      "self": "https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers/[ID]"
    }
  }
}

HTTP Status 200

HTTP Request

GET https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers/[ID]

Create Subscriber

curl -X POST -H "Content-type: application/json" \
  -H "X-USER-TOKEN: [USER TOKEN]" \
  -H "X-USER-EMAIL: [USER EMAIL]" \
  -d '{"data": {"attributes": {
        "email": "johnsmith@example.com",
        "first_name": "John",
        "last_name": "Smith"
      }}}' \
  https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers

<?php
  $url = 'https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers';
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'X-USER-TOKEN: [YOUR_AUTH_TOKEN]',
    'X-USER-EMAIL: [YOUR_EMAIL_ADDRESS]'
  ));

  $params = array('data' => array('attributes' => array(
    'email' => 'johnsmith@example.com',
    'first_name' => 'John',
    'last_name' => 'Smith'
  )));
  $params_string = json_encode($params);

  curl_setopt($ch, CURLOPT_POSTFIELDS, $params_string);

  curl_exec($ch);
  curl_close($ch);
?>

require 'faraday'
require 'faraday_middleware'

connection = Faraday.new(url: 'https://api.mailblast.io') do |f|
  f.headers['X-USER-TOKEN'] = '[YOUR_AUTH_TOKEN]'
  f.headers['X-USER-EMAIL'] = '[YOUR_EMAIL_ADDRESS]'
  f.request :json
  f.response :json
  f.adapter Faraday.default_adapter
end
connection.post('/v1/lists/[LIST_ID]/subscribers',
  {data: {attributes: {
    email: 'johnsmith@example.com',
    first_name: 'John',
    last_name: 'Smith'
  }}}
)

The above command returns the following JSON response:

{
  "data": {
    "id": "[ID]",
    "type": "subscribers",
    "attributes": {
      "email": "johnsmith@example.com",
      "first_name": "John",
      "last_name": "Smith",
      "state": "active",
      "created_at": "2017-01-01T00:00:00Z"
    },
    "links": {
      "self": "https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers/[ID]"
    }
  }
}

HTTP Status 201

This endpoint creates a new subscriber.

HTTP Request

POST https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers

Request Parameters

Parameter Description
email Email of the subscriber
first_name First Name of the subscriber
last_name Last name of the subscriber
state active or unsubscribed

Update Subscriber

curl -X PATCH -H "Content-type: application/json" \
  -H "X-USER-TOKEN: [USER_TOKEN]" \
  -H "X-USER-EMAIL: [USER_EMAIL]" \
  -d '{"data": {"attributes": {
        "email": "johnsmith@example2.com"
      }}}' \
  https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers/[ID]

<?php
  $url = 'https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers/[ID]';
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'X-USER-TOKEN: [YOUR_AUTH_TOKEN]',
    'X-USER-EMAIL: [YOUR_EMAIL_ADDRESS]'
  ));

  $params = array('data' => array('attributes' => array(
    'name' => 'List 1'
  )));
  $params_string = json_encode($params);

  curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'PATCH');
  curl_setopt($ch, CURLOPT_POSTFIELDS, $params_string);

  curl_exec($ch);
  curl_close($ch);
?>

require 'faraday'
require 'faraday_middleware'

connection = Faraday.new(url: 'https://api.mailblast.io') do |f|
  f.headers['X-USER-TOKEN'] = '[YOUR_AUTH_TOKEN]'
  f.headers['X-USER-EMAIL'] = '[YOUR_EMAIL_ADDRESS]'
  f.request :json
  f.response :json
  f.adapter Faraday.default_adapter
end
connection.patch('/v1/lists/[LIST_ID]/subscribers/[ID]',
  {
    data: {
      attributes: {
        state: 'unsubscribed'
      }
    }
  }
)

The above command returns the following JSON response:

{
  "data": {
    "id": "[ID]",
    "type": "subscribers",
    "attributes": {
      "email": "johnsmith@example2.com",
      "first_name": "John",
      "last_name": "Smith",
      "state": "active",
      "created_at": "2017-01-01T00:00:00Z"
    },
    "links": {
      "self": "https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers/[ID]"
    }
  }
}

HTTP Status 200

This endpoint updates a specific subscriber.

HTTP Request

PATCH https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers/[ID]

Request Parameters

Parameter Description
email Email of the subscriber
first_name First Name of the subscriber
last_name Last name of the subscriber
state active or unsubscribed

Delete Subscriber

curl -X DELETE \
  -H "X-USER-TOKEN: [USER TOKEN]" \
  -H "X-USER-EMAIL: [USER EMAIL]" \
  https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers/[ID]

<?php
  $url = 'https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers/[ID]';
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'X-USER-TOKEN: [YOUR_AUTH_TOKEN]',
    'X-USER-EMAIL: [YOUR_EMAIL_ADDRESS]'
  ));

  curl_setopt($curl, CURLOPT_CUSTOMREQUEST, 'DELETE');

  curl_exec($ch);
  curl_close($ch);
?>

require 'faraday'
require 'faraday_middleware'

connection = Faraday.new(url: 'https://api.mailblast.io') do |f|
  f.headers['X-USER-TOKEN'] = '[YOUR_AUTH_TOKEN]'
  f.headers['X-USER-EMAIL'] = '[YOUR_EMAIL_ADDRESS]'
  f.request :json
  f.response :json
  f.adapter Faraday.default_adapter
end
connection.delete('/v1/lists/[LIST_ID]/subscribers/[ID]')

The above command returns the following JSON response:

{}

HTTP Status 204

This endpoint deletes a specific subscriber from a list.

HTTP Request

DELETE https://api.mailblast.io/v1/lists/[LIST_ID]/subscribers/[ID]

Campaigns

Get All Campaigns

This endpoint retrieves all Campaigns.

curl \
  -H "X-USER-TOKEN: [USER_TOKEN]" \
  -H "X-USER-EMAIL: [USER_EMAIL]" \
  https://api.mailblast.io/v1/campaigns

<?php
  $url = 'https://api.mailblast.io/v1/campaigns';
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'X-USER-TOKEN: [USER_TOKEN]',
    'X-USER-EMAIL: [USER_EMAIL]'
  ));

  curl_exec($ch);
  curl_close($ch);
?>

require 'faraday'
require 'faraday_middleware'

connection = Faraday.new(url: 'https://api.mailblast.io') do |f|
  f.headers['X-USER-TOKEN'] = '[YOUR_AUTH_TOKEN]'
  f.headers['X-USER-EMAIL'] = '[YOUR_EMAIL_ADDRESS]'
  f.request :json
  f.response :json
  f.adapter Faraday.default_adapter
end
connection.get('/v1/campaigns')

The above command returns the following JSON response:

{
  "data": [
    {
      "id": "[ID]",
      "type": "campaigns",
      "attributes": {
        "name": "Campaign 1",
        "subject": "Campaign Subject 1",
        "state": "Campaign State",
        "created_at": "2017-01-01T00:00:00Z",
        "scheduled_at": "2017-01-01T00:00:00Z"
      },
      "links": {
        "self": "https://api.mailblast.io/v1/campaigns/[ID]"
      }
    }
  ],
  "links": {
    "self": "https://api.mailblast.io/v1/campaigns?page[number]=1&page[size]=15",
    "next": "https://api.mailblast.io/v1/campaigns?page[number]=2&page[size]=15",
    "last": "https://api.mailblast.io/v1/campaigns?page[number]=42&page[size]=15"
  }
}

HTTP Status 200

HTTP Request

GET https://api.mailblast.io/v1/campaigns

Request Parameters

Parameter Description Default
page[number] Returns the respective page 1
page[size] Items per page (max 100) 15

Get a specific Campaign

This endpoint retrieves a specific campaign.

curl \
  -H "X-USER-TOKEN: [USER_TOKEN]" \
  -H "X-USER-EMAIL: [USER_EMAIL]" \
  https://api.mailblast.io/v1/campaigns/[ID]

<?php
  $url = 'https://api.mailblast.io/v1/campaigns/[ID]';
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'X-USER-TOKEN: [USER_TOKEN]',
    'X-USER-EMAIL: [USER_EMAIL]'
  ));

  curl_exec($ch);
  curl_close($ch);
?>

require 'faraday'
require 'faraday_middleware'

connection = Faraday.new(url: 'https://api.mailblast.io') do |f|
  f.headers['X-USER-TOKEN'] = '[YOUR_AUTH_TOKEN]'
  f.headers['X-USER-EMAIL'] = '[YOUR_EMAIL_ADDRESS]'
  f.request :json
  f.response :json
  f.adapter Faraday.default_adapter
end
connection.get('/v1/campaigns/[ID]')

The above command returns the following JSON response:

{
  "data": {
    "id": "[ID]",
    "type": "campaigns",
    "attributes": {
      "name": "Campaign 1",
      "subject": "Campaign Subject 1",
      "state": "Campaign State",
      "open_count": 100,
      "click_count": 100,
      "bounce_count": 100,
      "unsubscribe_count": 100,
      "spam_complaint_count": 100,
      "created_at": "2017-01-01T00:00:00Z",
      "scheduled_at": "2017-01-01T00:00:00Z"
    },
    "links": {
      "self": "https://api.mailblast.io/v1/campaigns/[ID]"
    }
  }
}

HTTP Status 200

HTTP Request

GET https://api.mailblast.io/v1/campaigns/[id]

Create a Campaign

curl -X POST -H "Content-type: application/json" \
  -H "X-USER-TOKEN: [USER TOKEN]" \
  -H "X-USER-EMAIL: [USER EMAIL]" \
  -d '{"data": {"attributes": {
        "list_ids": 1,
        "name": "Campaign 1",
        "subject": "Campaign Subject 1",
        "body": "<html><p>Hello {{first_name}}</p></html>",
        "from_name": "No Reply",
        "from_email": "noreply@example.com"
      }}}' \
  https://api.mailblast.io/v1/campaigns

<?php
  $url = 'https://api.mailblast.io/v1/campaigns';
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'X-USER-TOKEN: [YOUR_AUTH_TOKEN]',
    'X-USER-EMAIL: [YOUR_EMAIL_ADDRESS]'
  ));

  $params = array('data' => array('attributes' => array(
    'list_ids' => 1,
    'name' => 'Campaign 1',
    'subject' => 'Campaign Subject 1',
    'body' => '<html><p>Hello {{first_name}}</p></html>',
    'from_name' => 'No Reply',
    'from_email' => 'noreply@example.com'
  )));
  $params_string = json_encode($params);

  curl_setopt($ch, CURLOPT_POSTFIELDS, $params_string);

  curl_exec($ch);
  curl_close($ch);
?>

require 'faraday'
require 'faraday_middleware'

connection = Faraday.new(url: 'https://api.mailblast.io') do |f|
  f.headers['X-USER-TOKEN'] = '[YOUR_AUTH_TOKEN]'
  f.headers['X-USER-EMAIL'] = '[YOUR_EMAIL_ADDRESS]'
  f.request :json
  f.response :json
  f.adapter Faraday.default_adapter
end
connection.post('/v1/campaigns',
  {data: {attributes: {
    list_ids: 1,
    name: 'Campaign 1',
    subject: 'Campaign Subject 1',
    body: '<html><p>Hello {{first_name}}</p></html>',
    from_name: 'No Reply',
    from_email: 'noreply@example.com'
  }}}
)

The above command returns the following JSON response:

{
  "data": {
    "id": "[ID]",
    "type": "campaigns",
    "attributes": {
      "click_count": 0,
      "created_at": "2017-01-01T00:00:00Z",
      "name": "Campaign 1",
      "open_count": 0,
      "recipient_count": 0,
      "spam_complaint_count": 0,
      "subject": "Campaign Subject 1",
      "unsubscribe_count": 0
    },
    "links": {
      "self": "https://api.mailblast.io/v1/campaigns/[ID]"
    }
  }
}

This endpoint creates a new campaign as a draft.

HTTP Request

POST https://api.mailblast.io/v1/campaigns

Request Parameters

Parameter Description Default
list_ids IDs of the subscriber lists the campaign will be sent to
name Name of campaign
subject Email subject of campaign
body Email subject of campaign
from_name From Name for your rmail
from_email From Address for your campaign

Schedule a Campaign

This endpoint schedule an existing campaign. Note this will not create the campaign, you must create the campaign using the create endpoint.

curl -X POST -H "Content-type: application/json" \
  -H "X-USER-TOKEN: [USER TOKEN]" \
  -H "X-USER-EMAIL: [USER EMAIL]" \
  -d '{"data": {"attributes": {
        "scheduled_at": "2017-01-01T00:00:00Z"
      }}}' \
  https://api.mailblast.io/v1/campaigns/[ID]/schedule

<?php
  $url = 'https://api.mailblast.io/v1/campaigns/[ID]/schedule';
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'X-USER-TOKEN: [YOUR_AUTH_TOKEN]',
    'X-USER-EMAIL: [YOUR_EMAIL_ADDRESS]'
  ));

  $params = array('data' => array('attributes' => array(
    'scheduled_at' => "2017-01-01T00:00:00Z",
  )));
  $params_string = json_encode($params);

  curl_setopt($ch, CURLOPT_POSTFIELDS, $params_string);

  curl_exec($ch);
  curl_close($ch);
?>

require 'faraday'
require 'faraday_middleware'

connection = Faraday.new(url: 'https://api.mailblast.io') do |f|
  f.headers['X-USER-TOKEN'] = '[YOUR_AUTH_TOKEN]'
  f.headers['X-USER-EMAIL'] = '[YOUR_EMAIL_ADDRESS]'
  f.request :json
  f.response :json
  f.adapter Faraday.default_adapter
end
connection.post('/v1/campaigns/[ID]/schedule',
  {data: {attributes: {
    scheduled_at: "2017-01-01T00:00:00Z"
  }}}
)

The above command returns the following JSON response:

{
  "data": {
    "id": "[ID]",
    "type": "campaigns",
    "attributes": {
      "name": "Campaign 1",
      "subject": "Campaign Subject 1",
      "open_count": 100,
      "click_count": 100,
      "bounce_count": 100,
      "unsubscribe_count": 100,
      "spam_complaint_count": 100,
      "created_at": "2017-01-01T00:00:00Z",
      "scheduled_at": "2017-01-01T00:00:00Z"
    },
    "links": {
      "self": "https://api.mailblast.io/v1/campaigns/[ID]"
    }
  }
}

HTTP Status 200

HTTP Request

POST https://api.mailblast.io/v1/campaigns/[id]/schedule

Request Parameters

Parameter Description Default
scheduled_at Schedule date of campaign

Archive a Campaign

This endpoint archive an existing campaign. Only sent campaigns can be archived.

curl -X POST -H "Content-type: application/json" \
  -H "X-USER-TOKEN: [USER TOKEN]" \
  -H "X-USER-EMAIL: [USER EMAIL]" \
  https://api.mailblast.io/v1/campaigns/[ID]/archive

<?php
  $url = 'https://api.mailblast.io/v1/campaigns/[ID]/archive';
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/json',
    'X-USER-TOKEN: [YOUR_AUTH_TOKEN]',
    'X-USER-EMAIL: [YOUR_EMAIL_ADDRESS]'
  ));

  curl_setopt($ch, CURLOPT_POSTFIELDS);

  curl_exec($ch);
  curl_close($ch);
?>

require 'faraday'
require 'faraday_middleware'

connection = Faraday.new(url: 'https://api.mailblast.io') do |f|
  f.headers['X-USER-TOKEN'] = '[YOUR_AUTH_TOKEN]'
  f.headers['X-USER-EMAIL'] = '[YOUR_EMAIL_ADDRESS]'
  f.request :json
  f.response :json
  f.adapter Faraday.default_adapter
end
connection.post('/v1/campaigns/[ID]/archive')

The above command returns the following JSON response:

{
  "data": {
    "id": "[ID]",
    "type": "campaigns",
    "attributes": {
      "name": "Campaign 1",
      "subject": "Campaign Subject 1",
      "open_count": 100,
      "click_count": 100,
      "bounce_count": 100,
      "unsubscribe_count": 100,
      "spam_complaint_count": 100,
      "created_at": "2017-01-01T00:00:00Z",
      "scheduled_at": "2017-01-01T00:00:00Z",
      "archived_at": "2017-01-01T00:00:00Z"
    },
    "links": {
      "self": "https://api.mailblast.io/v1/campaigns/[ID]"
    }
  }
}

HTTP Status 200

HTTP Request

POST https://api.mailblast.io/v1/campaigns/[id]/archive

Campaign Report

This endpoint retrieves all recipients of a campaign. You can pass in filter params to filter the recipients by state

curl \
  -H "X-USER-TOKEN: [USER_TOKEN]" \
  -H "X-USER-EMAIL: [USER_EMAIL]" \
  https://api.mailblast.io/v1/campaigns/[ID]/recipients

<?php
  $url = 'https://api.mailblast.io/v1/campaigns/[ID]/recipients';
  $ch = curl_init();

  curl_setopt($ch, CURLOPT_URL, $url);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    'X-USER-TOKEN: [USER_TOKEN]',
    'X-USER-EMAIL: [USER_EMAIL]'
  ));

  curl_exec($ch);
  curl_close($ch);
?>

require 'faraday'
require 'faraday_middleware'

connection = Faraday.new(url: 'https://api.mailblast.io') do |f|
  f.headers['X-USER-TOKEN'] = '[YOUR_AUTH_TOKEN]'
  f.headers['X-USER-EMAIL'] = '[YOUR_EMAIL_ADDRESS]'
  f.request :json
  f.response :json
  f.adapter Faraday.default_adapter
end
connection.get('/v1/campaigns/[ID]/recipients', {q: {opened: true}})

The above command returns the following JSON response:

{
  "data": [
    {
      "id": "[ID]",
      "type": "recipients",
      "attributes": {
        "email": "johnsmith@example.com",
        "first_name": "John",
        "last_name": "Smith",
        "state": "active",
        "open_count": 0,
        "click_count": 1,
        "sent_at": "2017-01-01T00:00:00Z"
      }
    }
  ],
  "links": {
    "self": "https://api.mailblast.io/v1/campaigns/[ID]/recipients?page[number]=1&page[size]=15",
    "next": "https://api.mailblast.io/v1/campaigns/[ID]/recipients?page[number]=2&page[size]=15",
    "last": "https://api.mailblast.io/v1/campaigns/[ID]/recipients?page[number]=42&page[size]=15"
  }
}

HTTP Status 200

HTTP Request

GET https://api.mailblast.io/v1/campaigns/[ID]/recipients

Request Parameters

Parameter Description Default
page[number] Returns the respective page 1
page[size] Items per page (max 100) 15
q[opened] Filter by opened
q[clicked] Filter by clicked
q[bounced] Filter by bounced
q[unsubscribed] Filter by unsubscribed
q[spam_complaint] Filter by spam_complaint

Errors

Error Code Meaning
401 Unauthorized -- Your API key is wrong
404 Not Found -- The specified resource could not be found
422 Unprocessible Entity -- Your request sucks
500 Internal Server Error -- We had a problem with our server. Try again later.
cURL PHP Ruby