API Calls

Overview Your First Call Subscribers Mailing Lists List Ai Campaigns Sender Profiles Send Campaign Analytics

Insight Tracking

Email Subscriber Management

Topics covered:

Introduction
Add A Subscriber
Update A Subscriber
Remove a Subscriber
Subscriber Search
Fetch Subscriber
Fetch Tags

Introduction

Subscriber management is the most commonly used area of the email blaster API. This allows your CRM or website to sync records with your email blaster. In this guide you will learn the basics of how to interact with your subscriber records, from: adding a subscriber, making amends to a record, removing a record and searching for a specific subscriber.

Add A Subscriber

This request will allow you to add a subscriber to an already existing mailing list inside your email blaster.

Note: Check out the mailing lists section to learn how to create a new mailing list, or fetch the ID number of an existing mailing list to make a subscribe request against.

To make a subscribe request, please make a POST request to the following address:

https://api.emailblaster.cloud/2.0/subscriber/subscribe

The request should be a JSON object containing your subscriber information:

{
       "salutation":"Mr",
       "first_name":"Chris",
       "surname":"Bob",
       "company":"bobs cakes ltd",
       "ref":"123456",
       "email":"chrisbob@example.com",
       "mobile":"07864765000",
       "tags": "18,36",
       "custom_fields": {
         "region": "UK",
         "account manager" : "Monty Parker"
       },
       "list":"257"
    }

Mandatory fields: email, list

Tags: You can optionally assign tags to your new subscriber. Tags help you segregate your list into subcategories. Your tags should be first created inside the software (not via the API). You can use the API to find the ID of your desired tag. Your subscribe request can contain the tag ID which you wish to assign to this subscriber. If adding multiple tags, they should be comma separated (as shown in the above example).

Custom Fields: Custom fields can be created inside Email Blaster (not via the API). Once set up, you can attach custom field data to any subscribe request. Each custom field should be referred to using its given name.

After a successful request, the following data will be returned. The value named 'subscriber_id' will contain the unique ID number of your newly added subscriber. You may wish to store this inside your CRM or database for making additional future calls against this subscriber.

{
   "status":"ok",
   "subscriber_id":92028
  }

Update A Subscriber

This call is made in order to make an update/amend to a subscriber record. For example, your subscriber may have a new preferred email address and you need to update your records accordingly.

To update a record, you will need to make a PATCH request. Your request should be made to the following URL:

https://api.emailblaster.cloud/2.0/subscriber/update/{id}

{id} should contain the subscriber_id which you wish to amend.

The request should be a JSON object containing your amended information. You only need to provide the data which you wish to update:

{
   "email":"jess@example.com",
   "mobile":"07654678000",
   "salutation":"Dr",
   "name":"Jess",
   "surname":"Glover",
   "company":"my company ltd",
   "ref":"abc123",
   "custom_fields": {
                "account manager": "Baxter Right",
                "region" : null
   },
   "tags" : "18,36",
   "list":"405",
   "status": "active"
}

Custom Fields: Sending across a null value against a custom field will remove this attribute from the user's contact card. You only need to send across custom field values which you wish to update.

Move New List: You can swap a subscriber to a new list by providing the new destination list id in the 'list' field.

Status:
{active} => Tag as an activate subscriber (will be included in mailings)
{bounced} => Tag as bounced/dead email address (will be excluded from mailings)
{unsubscribed} => Tag as unsubscribed (will be excluded from mailings)
{inactive} => Tag as inactive (will be excluded from mailings)

After a successful request, the following JSON response will be returned:

{"status":"ok"}

Remove A Subscriber

This request to the API can be used to remove / delete a subscriber from your email blaster. The update takes affect instantly, the subscriber will be removed from any existing or planned future sends.

This is a one way process, a deleted subscriber cannot be recovered. If you remove a subscriber by mistake, they can be re-added using a new subscribe request.

To remove a subscriber, you will need to make a DELETE request. This request should be made against the following URL:

https://api.emailblaster.cloud/2.0/subscriber/delete/{id}

{id} should contain the subscriber_id which you wish to remove.

After a successful request, the following JSON response will be returned:

{"status":"ok"}

Subscriber Search

The subscriber search function can be used to return the details of a specific subscriber, or set of subscribers against your own search criteria.

In the most basic form, if you know your subscriber_id, you can simply submit the subscriber_id.

You can also search by subscriber name, company name, email address or any item of data which will easily distinguish your subscriber from your database.

In each case the subscribers full contact card will be returned.

To perform a search, you will need to make a POST request. Your request should be made to the following URL:

https://api.emailblaster.cloud/2.0/subscriber/search

Your search request should contain the following JSON data:

{"search_string":"bob@example.com"}

A maxium of 25 records will be returned.

After a successful request, the following JSON response will be returned:

{
   "status":"ok",
   "matches":[
      {
         "id":67140,
         "salutation":"Mr",
         "first_name":"Paul",
         "surname":"Smith",
         "company":"Bob Cakes Ltd",
         "ref":"abc/123",
         "email":"paul.smith@example.com",
         "mobile":"07564667554",
         "custom_fields": {
                "region": "UK"
          },
         "list":"265",
         "list_name":"Weekly List",
         "tags": "18,36",
         "status": "active"
      },
      {
         "id":133,
         "salutation":"Mr",
         "first_name":"Bob",
         "surname":"Park",
         "company":"Bob Cakes Ltd",
         "ref":"dfg/456",
         "email":"bob.p@example.com",
         "mobile":"07564667555",
         "custom_fields": null,
         "list":"174",
         "list_name":"Latest Customers",
         "tags": "23",
         "status": "active"
      },
      {
         "id":739,
         "salutation":"Mr",
         "first_name":"Bob",
         "surname":"Keller",
         "company":"Keeper Ltd",
         "ref":"dfg/124",
         "email":"bob@example.com",
         "mobile":"07564667556",
         "custom_fields": null,
         "list":"174",
         "list_name":"Latest Customers",
         "tags": "23",
         "status": "bounced"
      },
      {
         "id":1345,
         "salutation":"Mr",
         "first_name":"Bob",
         "surname":"Shaker",
         "company":"Shaker Ltd",
         "ref":"165/fgt",
         "email":"bob.s@example.com",
         "mobile":"07564667557",
         "custom_fields": {
                "region": "UK"
          },
         "list":"175",
         "list_name":"New Final Ai test B4",
         "tags": "",
         "status": "unsubscribed"
      },
      {
         "id":22588,
         "salutation":"Mr",
         "first_name":"Bob",
         "surname":"Lark",
         "company":" Lark Pies Ltd",
         "ref":"",
         "email":"bob.lark@example.com",
         "mobile":"07564667558",
         "custom_fields": {
                "region": "GB"
          },
         "list":"181",
         "list_name":"Group One",
         "tags": "",
         "status": "active"
      },
      {
         "id":22006,
         "salutation":"Dr",
         "first_name":"Bob",
         "surname":"Keeper",
         "company":"Bob The Dr",
         "ref":"452/56f",
         "email":"bob.keeper@example.com",
         "mobile":"07564667559",
         "custom_fields": null,
         "list":"181",
         "list_name":"Group One",
         "tags": "",
         "status": "inactive"
      },
      {
         "id":5204,
         "salutation":"Mr",
         "first_name":"Bob",
         "surname":"Bird",
         "company":" Bird Ltd",
         "ref":"45f/fhj",
         "email":"boberster@example.com",
         "mobile":"07564667560",
         "custom_fields": null,
         "list":"174",
         "list_name":"Latest Customers",
         "tags": "",
         "status": "active"
      },
      {
         "id":7898,
         "salutation":"Mr",
         "first_name":"Bob",
         "surname":"Smiths",
         "company":"JPop Ltd",
         "ref":"4345/ffd",
         "email":"bob@example.com",
         "mobile":"07564667561",
         "custom_fields": null,
         "list":"237",
         "list_name":"June Subscribes",
         "tags": "2,3",
         "status": "active"
      }
   ]
}

Fetch Subscriber

The subscriber fetch function can be used to return the details of a specific subscriber. This request is used when you already know the subscriber's ID and wish to pull the full contact card for this user.

To perform a fetch request, you will need to make a GET lookup to the following URL:

https://api.emailblaster.cloud/2.0/subscriber/fetch/{id}

After a successful request, the following JSON response will be returned:


  {
   "status":"ok",
   "subscriber":{
      "id":186099,
      "salutation":"Dr",
      "first_name":"Jess",
      "surname":"Glover",
      "company":"my company ltd",
      "ref":"abc123",
      "email":"jess@example.co.uk",
      "mobile":"07564667561",
      "custom_fields": {
             "region": "GB"
       },
      "list":"118",
      "list_name":"June list",
      "tags": "18,36",
      "status": "active"
   }
}

Fetch Tags

You can optionally assign tags to a subscriber, this helps segregate your list into subcategories. Tags should be first created inside the software (not via the API).

After creating your tags, use this call to find out the ID number of each tag. The ID number can be referenced in future API calls - such as add subscribing a new user and assigning custom tags to that contact.

To list all tags on a mailing list, you will need to make a GET request. This request should be made against the following URL:

https://api.emailblaster.cloud/2.0/subscriber/fetchtags/{list_id}

After a successful request, the following JSON response will be returned:


  {
   "status":"ok",
   "tags":{
      "112":"API Subscribers",
      "113":"Hot Leads",
      "114":"Website Subscribers"
   }
}