NAV Navbar

Mailblast API Docs

cURL PHP Ruby
  • Introduction
  • Lists
  • Subscribers
  • Campaigns
  • Errors
  • 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/api/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/api/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 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

    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/api/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.