Gestion des abonnés
Récupérer les informations d'un abonné
Pour récupérer les informations d'un abonné ou vérifier s'il est présent en base de données, vous devez faire un GET api/{idsite}/Subscribers
Les paramètres a spécifier dans l'url sont les suivants:
| Nom | Description | Type | Informations complémentaires |
|---|---|---|---|
| idsite | Identifiant de site MindBaz | Nombre entier | Obligatoire |
| filter.by | indique ce que contient filter.values. Les valeurs possibles sont "IdSubscriber","IdClient","Email". | String | Obligatoire |
| filter.values | Liste des valeurs à rechercher (séparés par des virgules) ex : email1@domain.com,email2@domain.com | String | Obligatoire |
| filter.idFields | Liste d'identifiants de champs séparés par des virgules (ex:0,1,7) | string | Aucune |
| filter.emailEncoding | A rensigner si l'email est encodé. Les valeurs possibles sont "NONE", "MD5", "SHA1", "SHA2_256", "SHA2_512". | String | optionnel, par defaut emailEncoding = NONE |
Vous pouvez rechercher un abonné en fonction de :
- son email : l'email stocké dans le field id 1. Vous pouvez aussi passer un email encodé (MD5, SHA2_256...) mais il faut renseigner l'encodage utilisé dans filter.emailEncoding. Attention, il ne faut pas mettre le 0x dans l'email encodé. Ex : 89D1DEEA9F6C6637964083C98E986B30
- son id : l'identifiant de l'abonné (field id 0)
- son idClient : votre propre identifiant client à stocker dans le champ field id 43
Pour des raisons de performance, il est fortement conseillé de fournir une liste de champs dans le paramètre filter.idFields et de ne pas récupérer tous les champs. Ne demandez que les champs dont vous avez besoin. Par ex, si vous faites un GET pour vérifier si l'abonné existe, utilisez filter.idFields=0 pour ne récupérer en retour que son id.
Les champs les plus souvent utilisés sont :
- 0 : id
- 1 : email
- 3 : dernière date d'abonnement
- 7 : statut de l'abonnement
- 13 : civilité
- 14 : nom
- 15 : prénom
En réponse, l'api retourne un tableau d'objets Subscriber contenant les champs demandés en entrée dans le paramètre filter.idFields.
Le type Subscriber contient les champs suivant:
| Nom | Description | Type |
|---|---|---|
| id | Identifiant de l'abonné | Nombre entier |
| fields | Champs contenant les informations de l'abonné | Collection de SubscriberFieldData |
Le type SubscriberFieldData est une collection de champs "clé/valeur" représentant comme suit:
| Nom | Description | Type |
|---|---|---|
| idField | Identifiant du champ (0 = id, 1 =email...) | Nombre entier |
| value | Valeur du champ (string, datetime, integer ou byte) | Object |
Un appel API est disponible afin de récupérer la valeur "idField du champs à mettre à jour, voir la partie Gestion des champs depuis le menu.
Cette article du centre d'aide vous aidera à mieux comprendre la gestion des champs d'un abonné dans Mindbaz.
Ajouter un abonné dans la base de données
Afin d'ajouter un abonné dans votre base de données, vous devez faire un appel POST api/{idsite}/Subscribers. Cette api peut servir aussi à créer plusieurs abonnés.
Avant d'ajouté un abonné en base, vous devez vérifier s'il n'existe pas déjà. Vous ne pouvez pas créer 2 abonnés avec la même adresse email.
Les paramètres à spécifier dans l'url sont les suivants:
| Nom | Description | Type | Informations complémentaires |
|---|---|---|---|
| idsite | Identifiant de site MindBaz | Nombre entier | Obligatoire |
Dans le corps de la requête, les paramètres à passer sous la forme "application/json, text/json" sont un tableau d'objets Subscriber. Le type Subscriber contient les champs suivant:
| Nom | Description | Type | Informations complémentaires |
|---|---|---|---|
| id | Identifiant de l'abonné (correspond également au champ field id=0) | Nombre entier | Pour une création, vous pouvez omettre ce champ ou passer la valeur -1 |
| fields | Champs contenant les informations de l'abonné | Collection de SubscriberFieldData | Obligatoire |
Le type SubscriberFieldData est une collection de champs "clé/valeur" représentant comme suit:
| Nom | Description | Type | Informations complémentaires |
|---|---|---|---|
| idField | Identifiant du champ (0 = id, 1 =email...) | Nombre entier | Obligatoire |
| value | Valeur du champ (string, datetime, integer ou byte) | Object | Obligatoire |
Si vous ne renseignez pas de valeur pour les champs d'abonnement, un email sera automatiquement inséré en statut "abonné" avec une date d'abonnement = "maintenant" (dans les champs 2 et 3) et un statut = "abonné" (dans le champ 7).
Cas d'utilisation : collecte de l'email "montest@domain.com"
Je souhaite ajouter un abonné avec la valeur "montest@domain.com" dans le champs Email et la valeur "abonné" dans le champs "état de l'abonné".
Je vérifie si l'email existe en base. Pour cela, je fais un GET sur api/{idsite}/Subscribers?filter.by=Email&filter.values=montest@domain.com&filter.idFields=0,7.
Ici, je demande les idFields 0 et 7 pour connaitre l'id et le statut de son abonnement.
Comme l'abonné n'existe pas, j'obtiens ce retour :
{
"success": true,
"data": null,
"error": null,
"typeName": "Subscriber[]"
}
Si l'abonné existait, j'aurais obtenu son id en retour:
{
"success": true,
"data": [
{
"id": 123456,
"fields": [
{
"idField": 0,
"value": 123456
},
{
"idField": 7,
"value": 0
}
]
}
],
"error": null,
"typeName": "Subscriber[]"
}
Un statut "abonné" correspond à la valeur 0.
Voici les différentes valeurs possible pour le statut d'abonnement : 0:Abonné;1:Désabonné;2:Désabonnement manuel;3:Assainissement / Domaine invalide;4:Assainissement / Syntaxe invalide;5:Assainissement / Liste repoussoir;6:Assainissement / Doublon;7:Assainissement NPAI;8:En attente de confirmation d'inscription;9:Spam;10:En attente de validation;11:Test FAI;12:Désabonnement groupe
Pour insérer le nouvel abonné en base, je fais un POST sur api/{idsite}/Subscribers. Comme c'est une création, je ne spécifie pas le champs "id" de l'utilisateur.
[
{
"fields": [
{
"idField": 1,
"value": "montest@domain.com"
},
{
"idField": 7,
"value": 0
}
]
}
]
En retour d'appel j'obtiens les informations de l'abonné nouvellement créé:
{
"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[]"
}
Lorsque vous collectez des abonnés, nous vous conseillons d'utiliser les champs première provenance (field id 5) et dernière provenance (field id 6) pour y stocker l'origine de collecte de l'adresse email. Les champs Mode de collecte (field id 21) et Type de collecte (field id 22) ont été créé également pour vous aider à catégoriser les provenances de votre collecte.
Une api subscriptions a été créée spécialement pour vous aider à mieux gérer vos abonnements.
- Pour abonner un email deja existant en base, vous pouvez faire un PUT sur /api/{idsite}/subscriptions
- Pour abonner un nouvel email, vous pouvez faire un POST sur /api/{idsite}/subscriptions/new
Une validation de l'email est faite avant l'insertion en base. Si l'email n'est pas valide, l'insertion n'est pas faite! Dans ce cas, l'api retourne quand même un success:true mais avec un id:-1 pour cet email.
Mise à jour d'un abonné dans la base de données
La mise a jour d'un abonné fonctionne comme la création. Il faut vérifier si l'email exite en base, récupérer son id et le passer dans le paramètre id en faisant un PUT api/{idsite}/Subscribers.
Cas d'utilisation 2 :Mise à jour de l'abonné
Je souhaite mettre à jour l'abonné précédement créé en passant son "état abonné" à désabonné. Je n'oublie pas de mettre à jour aussi la date de désabonnement (field id 4). Je fais un PUT sur api/{idsite}/Subscribers :
Comme c'est une mise à jour sur un abonné existant, je spécifie le champs "id" de l'utilisateur précédement créé.
[
{
"id": 723081,
"fields": [
{
"idField": 7,
"value": 1
},
{
"idField": 4,
"value": "2023/01/04 17:39"
}
]
}
]
En retour j'obtiens la confirmation de la mise à jour du champs
{
"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[]"
}
Modifier plusieurs abonnés
Pour les appels POST et PUT, le paramètre d'entrée subscribers est une collection. Il est donc possible de mettre à jour n abonné(s) en un seul appel (avec un max de 5000 abonnés).
Par exemple pour créer plusieurs abonnés dans le même appel, je fais un POST avec :
[
{
"fields": [
{
"idField": 1,
"value": "montest@domain.com"
},
{
"idField": 7,
"value": 0
}
]
},
{
"fields": [
{
"idField": 1,
"value": "montestbis@domain.com"
},
{
"idField": 7,
"value": 0
}
]
}
]
si vous voulez faire des modifications et des insertions dans le même appel, cela est possible avec le POST. Si vous fournissez un id de subscriber valide au POST, il fera également la mise à jour de ses champs!
Si une erreur intervient au milieu de la collection, cela interrompt le traitement et les emails suivants ne sont pas traités.
Si vous avez de gros volumes d’abonnés à insérer en base de données, nous vous conseillons d’utiliser l’api d’import pour cela. Vous aurez de meilleures performances!”