Abonnés

Le cas typique : votre boutique inscrit ses clients à la liste « Clients », pose des tags selon ce qu’ils achètent, et répercute les désabonnements.

Tous les exemples utilisent $LEKALAO_TOKEN (jeton Lecture et écriture) et $LIST, l’id de la liste. L’id d’une liste est dans GET /api/v1/lists.

Inscrire une personne

curl -X POST https://lekalao.example.com/api/v1/lists/$LIST/subscribers \
  -H "Authorization: Bearer $LEKALAO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "email": "ada@example.com",
    "first_name": "Ada",
    "last_name": "Lovelace",
    "locale": "fr",
    "timezone": "Africa/Douala",
    "attributes": { "ville": "Douala", "client_depuis": "2024-03-01" },
    "tags": ["client", "pain-complet"]
  }'

Réponse 201 :

{
    "data": {
        "id": "5f0e7c1b-2d4a-4e8f-b1c3-9a7d6e5f4b3a",
        "email": "ada@example.com",
        "first_name": "Ada",
        "last_name": "Lovelace",
        "timezone": "Africa/Douala",
        "locale": "fr",
        "status": "unconfirmed",
        "tags": ["client", "pain-complet"],
        "attributes": { "ville": "Douala", "client_depuis": "2024-03-01" },
        "subscribed_at": null,
        "unsubscribed_at": null,
        "created_at": "2026-09-17T10:02:11+00:00"
    }
}

Gardez l’id dans votre base : c’est lui qui désigne la personne dans les appels suivants.

Ce qui se passe selon les cas

Cas	Résultat
Nouvelle adresse, liste sans double opt-in	`status: subscribed`. Les automatisations d’inscription démarrent.
Nouvelle adresse, liste en double opt-in	`status: unconfirmed`, e-mail de confirmation envoyé.
Idem avec `"skip_confirmation": true`	`status: subscribed` directement.
Adresse déjà abonnée	Mise à jour. Les champs vides ne remplacent rien, les attributs sont fusionnés, les tags s’ajoutent.
Adresse désabonnée	Réabonnée, avec confirmation si la liste l’exige.
Adresse dans la liste de suppression	`422` « This address is blocked. »
Limite d’abonnés de la formule atteinte	`422` avec le message de la formule.

skip_confirmation et la réinscription des désabonnés engagent votre responsabilité. N’inscrivez directement que des personnes dont vous avez le consentement, et ne renvoyez pas à Lekalao quelqu’un qui s’est désabonné : écoutez le webhook subscriber.unsubscribed pour mettre votre base à jour.

Les adresses sont enregistrées en minuscules, sans espaces autour.

Inscrire en lot

Jusqu’à 1 000 personnes en un appel, par exemple pour une synchronisation nocturne :

curl -X POST https://lekalao.example.com/api/v1/lists/$LIST/subscribers/batch \
  -H "Authorization: Bearer $LEKALAO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "subscribers": [
      { "email": "ada@example.com", "first_name": "Ada", "tags": ["client"] },
      { "email": "grace@example.com", "first_name": "Grace", "attributes": { "ville": "Yaoundé" } }
    ],
    "skip_confirmation": false,
    "replace_tags": false
  }'

Jusqu’à 100 lignes, la réponse arrive tout de suite, ligne par ligne :

{
    "data": [
        {
            "index": 0,
            "email": "ada@example.com",
            "id": "5f0e…",
            "outcome": "already_subscribed"
        },
        {
            "index": 1,
            "email": "grace@example.com",
            "id": "8b2d…",
            "outcome": "pending"
        }
    ],
    "meta": { "added": 1, "updated": 1, "failed": 0 }
}

`outcome`	Signification
`subscribed`	Inscrite.
`pending`	En attente de confirmation.
`already_subscribed`	Déjà là ; fiche mise à jour.
`failed`	Refusée (adresse bloquée, formule pleine). Le motif est dans `message`.

Une ligne refusée ne fait pas échouer les autres. Si toutes échouent, le code est 422. Au-delà de 100 lignes, le lot part en arrière-plan comme un import. La réponse est 202 avec l’import à suivre :

{
    "data": {
        "id": "c41a…",
        "status": "pending",
        "file_name": "API batch of 850",
        "url": "https://lekalao.example.com/api/v1/imports/c41a…"
    },
    "meta": { "queued": 850 }
}

Interrogez GET /api/v1/imports/{id} jusqu’à status: completed ou failed. Les compteurs added, updated, failed et le détail des errors y sont. replace_tags: true remplace les tags de chaque personne par ceux de sa ligne, au lieu de les ajouter.

Importer un fichier

Pour un fichier CSV ou Excel déjà prêt, envoyez-le tel quel :

curl -X POST https://lekalao.example.com/api/v1/lists/$LIST/imports \
  -H "Authorization: Bearer $LEKALAO_TOKEN" \
  -H "Accept: application/json" \
  -F "file=@clients.csv" \
  -F "tags[]=import-septembre" \
  -F "mapping[E-mail]=email" \
  -F "mapping[Prénom]=first_name" \
  -F "mapping[Ville]=attribute:ville"

Sans mapping, les colonnes sont reconnues d’après leur titre. Les personnes importées sont inscrites sans e-mail de confirmation, et les désabonnés ne sont réinscrits que si resubscribe_unsubscribed vaut true. Voir Import et export.

Retrouver quelqu’un

# Par adresse
curl "https://lekalao.example.com/api/v1/lists/$LIST/subscribers?email=ada@example.com" \
  -H "Authorization: Bearer $LEKALAO_TOKEN" -H "Accept: application/json"

# Les nouveaux abonnés depuis hier, par tag
curl "https://lekalao.example.com/api/v1/lists/$LIST/subscribers?status=subscribed&tag=client&since=2026-09-16" \
  -H "Authorization: Bearer $LEKALAO_TOKEN" -H "Accept: application/json"

Filtre	Valeurs
`status`	`subscribed`, `unconfirmed`, `unsubscribed`
`email`	Une adresse exacte.
`tag`	Le nom d’un tag.
`since`	Créés depuis cette date.
`sort`, `direction`	`email` ou l’ordre de création ; `asc` ou `desc` (défaut).

GET /api/v1/subscribers/{id} lit une personne.

Mettre à jour

curl -X PUT https://lekalao.example.com/api/v1/subscribers/$SUBSCRIBER \
  -H "Authorization: Bearer $LEKALAO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "first_name": "Ada", "locale": "en", "attributes": { "ville": "Kribi", "points": 120 } }'

Un champ absent ou null ne change pas.
attributes, s’il est envoyé, remplace tous les attributs.
tags, s’il est envoyé, remplace tous les tags.

Poser et retirer des tags

Pour ajouter ou retirer sans connaître les autres tags :

curl -X POST https://lekalao.example.com/api/v1/subscribers/$SUBSCRIBER/tags \
  -H "Authorization: Bearer $LEKALAO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{ "add": ["panier-abandonné"], "remove": ["a-commandé"] }'

Un tag qui n’existe pas encore sur la liste est créé. Poser un tag peut démarrer une automatisation. Les tags de la liste se lisent avec GET /api/v1/lists/{id}/tags et se créent à l’avance avec POST /api/v1/lists/{id}/tags.

Désabonner, réabonner, supprimer

Appel	Effet
`POST /subscribers/{id}/unsubscribe`	Désabonne. La personne reste dans la liste et dans les statistiques.
`POST /subscribers/{id}/resubscribe`	Réabonne sans confirmation. `422` si l’adresse est bloquée.
`POST /subscribers/{id}/resend-confirmation`	Renvoie l’e-mail de confirmation. `422` si la personne n’est pas en attente.
`DELETE /subscribers/{id}`	Supprime la fiche. Préférez le désabonnement, qui garde l’historique.

En PHP

use Illuminate\Support\Facades\Http;

$lekalao = Http::withToken(config('services.lekalao.token'))
    ->baseUrl('https://lekalao.example.com/api/v1')
    ->acceptJson()
    ->retry(3, 500, throw: false);

$response = $lekalao->post("lists/{$listUuid}/subscribers", [
    'email' => $customer->email,
    'first_name' => $customer->first_name,
    'locale' => $customer->locale,
    'tags' => ['client'],
]);

if ($response->successful()) {
    $customer->update(['lekalao_id' => $response->json('data.id')]);
}

En JavaScript (Node)

const response = await fetch(
    `https://lekalao.example.com/api/v1/lists/${listUuid}/subscribers`,
    {
        method: 'POST',
        headers: {
            Authorization: `Bearer ${process.env.LEKALAO_TOKEN}`,
            'Content-Type': 'application/json',
            Accept: 'application/json',
        },
        body: JSON.stringify({
            email: 'ada@example.com',
            first_name: 'Ada',
            tags: ['client'],
        }),
    },
);

if (response.status === 422) {
    const { message, errors } = await response.json();
    console.warn(message, errors);
}

L'API

Recettes

Intégrations

Inscrire une personne

Ce qui se passe selon les cas

Inscrire en lot

Importer un fichier

Retrouver quelqu’un

Mettre à jour

Poser et retirer des tags

Désabonner, réabonner, supprimer

En PHP

En JavaScript (Node)

​Inscrire une personne

​Ce qui se passe selon les cas

​Inscrire en lot

​Importer un fichier

​Retrouver quelqu’un

​Mettre à jour

​Poser et retirer des tags

​Désabonner, réabonner, supprimer

​En PHP

​En JavaScript (Node)

Inscrire une personne

Ce qui se passe selon les cas

Inscrire en lot

Importer un fichier

Retrouver quelqu’un

Mettre à jour

Poser et retirer des tags

Désabonner, réabonner, supprimer

En PHP

En JavaScript (Node)