Susbscriber management

Retrieving Subscriber Information

To retrieve a subscriber's information or to check if it is present in the database, you must do a GET api/{idsite}/Subscribers

The parameters to specify in the url are the following:

Name	Description	Type	Additional information
idsite	MindBaz site identifier	Integer	Mandatory
filter.by	indicates what filter.values contains. Possible values are "IdSubscriber", "IdClient", "Email".	String	Mandatory
filter.values	List of values to search for (separated by commas) e.g.: email1@domain.com,email2@domain.com	String	Mandatory
filter.idFields	Comma-separated list of field identifiers (ex:0,1,7)	string	None
filter.emailEncoding	if the email is encoded. Possible values are "NONE", "MD5", "SHA1", "SHA2_256", "SHA2_512".	string	optional, default emailEncoding = NONE

You can search for a subscriber based on :

his "email": the email stored in the field id 1. You can also pass an encoded email (MD5, SHA2_256...) but you have to inform the encoding used in filter.emailEncoding. Be careful, you must not put the 0x in the encoded email. Ex : 89D1DEEA9F6C6637964083C98E986B30
its "id": the subscriber's identifier (field id 0)
its "IdClient": your own customer id to be stored in the field id 43

Best pratice

For performance reasons, it is strongly advised to provide a list of fields in the filter.idFields parameter and not to retrieve all the fields. Only request the fields you need. For example, if you do a GET to check if the subscriber exists, use filter.idFields=0 to retrieve only the subscriber's id.

The most commonly used fields are :

0: id
1 : email
3 : last subscription date
7 : subscription status
13 : title
14 : last name
15 : first name

In response, the api returns an array of Subscriber objects containing the fields requested as input in the filter.idFields parameter.

The Subscriber type contains the following fields:

Name	Description	Type
id	Subscriber ID	Integer
fields	Fields containing subscriber information	Collection of SubscriberFieldData

The SubscriberFieldData type is a collection of "key/value" fields representing the following:

Name	Description	Type
idField	Field identifier (0 = id, 1 =email...)	Integer
value	Field value (string, datetime, integer or byte)	Object

Info

An API call (https://learn.mindbaz.com/api/#operation/Fields_Get) is available to retrieve the "idField value of the field to be updated, see the section Field management from the menu.

This Help Center article will help you better understand how to manage subscriber fields in Mindbaz.

Add a subscriber to the database

In order to add a subscriber to your database, you must make a POST api/{idsite}/Subscribers call. This api can also be used to create multiple subscribers.

Attention

Before adding a subscriber to the database, you have to check if it does not already exist. You cannot create 2 subscribers with the same email address.

The parameters to specify in the url are the following:

Name	Description	Type	Additional information
idsite	MindBaz site identifier	Integer	Mandatory

In the request body, the parameters to be passed as "application/json, text/json " are an array of Subscriber objects. The Subscriber type contains the following fields:

Name	Description	Type	Additional information
id	Subscriber ID (also corresponds to id=0)	Integer	For a creation, you can omit this field or pass the value -1
fields	Fields containing subscriber information	Collection of SubscriberFieldData	Mandatory

The SubscriberFieldData type is a collection of "key/value" fields representing the following:

Name	Description	Type	Additional information
idField	Field identifier (0 = id, 1 =email...)	Integer	Mandatory
value	Value of the field (string, datetime, integer or byte)	Object	Mandatory

default fields

If you leave the subscription fields blank, an email will automatically be inserted as "subscribed" with a subscription date = "now" (in fields 2 and 3) and a status = "optin" (in field 7).

Use case : collect email "montest@domain.com"

I want to add a subscriber with the value "montest@domain.com" in the field Email and the value "optin" in the field "subscriber status":

I check if the email exists in the database. To do this, I do a GET on api/{idsite}/Subscribers?filter.by=Email&filter.values=montest@domain.com&filter.idFields=0,7.

Here, I ask for idFields 0 and 7 to find out the id and status of his subscription.

As the subscriber does not exist, I get this return:

{
  "success": true,
  "data": null,
  "error": null,
  "typeName": "Subscriber[]"
}

If the subscriber existed, I would have gotten his id in return:

{
  "success": true,
  "data": [
    {
      "id": 123456,
      "fields": [
        {
          "idField": 0,
          "value": 123456
        },
        {
          "idField": 7,
          "value": 0
        }
      ]
    }
  ],
  "error": null,
  "typeName": "Subscriber[]"
}

INFO

A "optin" status corresponds to the value 0.

Here are the different possible values for the subscription status : 0:optin;1:optout;2:manual optout;3:Cleaning / Invalid domain;4:Cleaning / invalid synthax;5:cleaning / Blacklist;6:cleaning / double;7:cleaning / Bounce;8:Pending subscription confirmation;9:SPAM;10:Pending approval;11:TEST FAI;12:group optout

To insert the new subscriber into the base, I do a POST on api/{idsite}/Subscribers. As it is a creation, I do not specify the "id" field of the user.

[
  {
    "fields": [
      {
        "idField": 1,
        "value": "montest@domain.com"
      },
      {
        "idField": 7,
        "value": 0
      }
    ]
  }
]

In return for the call I get the information of the newly created subscriber:

{
  "success": true,
  "data": [
    {
      "id": 723081,
      "fields": [
        {
          "idField": 0,
          "value": 723081
        },
        {
          "idField": 1,
          "value": "montest@domain.com"
        },
        {
          "idField": 2,
          "value": "2021-08-24T15:00:29.409141+02:00"
        },
        {
          "idField": 3,
          "value": "2021-08-24T15:00:29.409141+02:00"
        },
        {
          "idField": 7,
          "value": 0
        },
        {
          "idField": 37,
          "value": "domain.com"
        }
      ]
    }
  ],
  "error": null,
  "typeName": "Subscriber[]"
}

info

When collecting subscribers, we recommend that you use the first source (field id 5) and last source (field id 6) fields to store the origin of the email address collection. The Collection Mode (field id 21) and Collection Type (field id 22) fields have also been created to help you categorise the origins of your collection.

A subscriptions API has been created specifically to help you better manage your subscriptions.

To subscribe to an existing email, you can do a PUT on /api/{idsite}/subscriptions
To subscribe a new email, you can POST to /api/{idsite}/subscriptions/new

Be careful

A validation of the email is done before insertion in the database. If the email is not valid, the insertion is not done! In this case, the api still returns a success:true but with an id:-1 for this email.

Update a subscriber in the database

Updating a subscriber works like creating one. You have to check if the email exists in the database, get its id and pass it in the id parameter by doing a PUT api/{idsite}/Subscribers.

Use Case 2: Subscriber update

I want to update the previously created subscriber by changing its "subscriber status" to unsubscribed. I don't forget to update also the unsubscription date (field id 4). I do a PUT on api/{idsite}/Subscribers :

As this is an update on an existing subscriber, I specify the "id" field of the previously created user.

[
  {
    "id": 723081,
    "fields": [
      {
        "idField": 7,
        "value": 1
      },
      {
        "idField": 4,
        "value": "2023/01/04 17:39"
      }
    ]
  }
]

In return I get the confirmation of the update of the field

{
  "success": true,
  "data": [
    {
      "id": 723081,
      "fields": [
        {
          "idField": 0,
          "value": 723081
        },
        {
          "idField": 7,
          "value": 1
        },
        {
          "idField": 4,
          "value":"2023-01-04T17:39:00+01:00"
        }
      ]
    }
  ],
  "error": null,
  "typeName": "Subscriber[]"
}

Edit multiple subscribers

For POST and PUT calls, subscribers input parameter is a collection. It is therefore possible to update n subscribers in a single call (with a maximum of 5000 subscribers).

For example to create several subscribers in the same call, I do a POST with :

[
  {
    "fields": [
      {
        "idField": 1,
        "value": "montest@domain.com"
      },
      {
        "idField": 7,
        "value": 0
      }
    ]
  },
  {
    "fields": [
      {
        "idField": 1,
        "value": "montestbis@domain.com"
      },
      {
        "idField": 7,
        "value": 0
      }
    ]
  }
]

info

if you want to make changes and inserts in the same call, this is possible with the POST. If you provide a valid subscriber id to the POST, it will also update its fields!

attention

If an error occurs in the middle of the collection, it stops the processing and the following emails are not processed.

Best practice

If you have large volumes of subscribers to insert into the database, we advise you to use the import api for this. You will have better performance!

Retrieving Subscriber Information​

Add a subscriber to the database​

Use case : collect email "montest@domain.com"​

Update a subscriber in the database​

Use Case 2: Subscriber update​

Edit multiple subscribers​