Documentation de l’API d’Emailicious¶

Table des matières¶

Sujets¶

Introduction¶

L’API d’Emailicious expose une collection de ressources via un interface HTTP REST.

La racine de l’API est exposée au chemin /api/v1 de chaque compte Emailicious existant:

https://<account>.emailicious.com/api/v1

Authentification¶

L’accés aux ressources exposées via l’API requiert une authentication préablable

Toutes les requêtes doivent inclure un entête Authorization afin de permettre une authentication basic HTTP à partir d’un nom d’usager existant et son mot de passe associé.

GET /api/v1 HTTP/1.1
Host: account.emailicious.com
Authorization: Basic Zm9vOmJhcg==

À défaut de fournir des données d’authentication valide une réponse 401 Unauthorized sera retournée.

HTTP/1.1 401 UNAUTHORIZED
Content-Type: application/json
WWW-Authenticate: Basic realm="api"

{
    "detail": "Invalid username/password."
}

Note

Les noms d’usager Emailicious contiennent le caractère « @ » qui est aussi utilisé comme séparateur des sections credentials et host d’une URI. La plupart des clients HTTP s’assurent d’appliquer l’encodage-pourcentage au nom d’usager ainsi qu’au mot de passe mais il est possible que vous deviez effectuer la substitution vous même si ce n’est pas le cas.

Par exemple, l’outil de ligne de commande cURL requiert telle manipulation:

curl https://user%40domain.com:password@account.emailicious.com/api/v1

Erreurs¶

Erreurs client¶

Lorsqu’une requête HTTP à l’API est malformée une réponse dont le code de statut est 4XX est retourné.

400 Bad Request ¶

Si vous tentiez de modifier ou de créer une ressource il est possible que les données fournies soit invalide (Un champs requis manquant, une adresse courriel invalide, …). Référez vous au corps de la réponse pour plus de détails.

401 Unauthorized ¶

Les données d’authentifications sont invalides. Référez-vous à la section authentification pour plus de détails.

404 Not Found ¶

La ressource spécifée n’existe pas ou n’est plus accessible. Assurez-vous que l’URI spécifiée est bien valide.

409 Conflict ¶

La tentative d’altération de la ressource cause un conflit. Plus de détails devraient être disponible dans le corps de la réponse et une stratégie de résolution du conflit devrait être exposée via la documentation de la ressource concernée.

Erreurs serveur¶

Lorsque les serveurs d’Emailicious ne sont pas en mesure de traiter une requête adéquatement une réponse dont le code de statut est 5XX est retournée. De telles occurrences sont rares et intermittentes et vous devriez contacter notre équipe de support si le problème devait persister.

500 Internal Server Error ¶

Les serveurs d’Emailicious ont rencontré un problème lors du traitement de votre requête et nos développeurs travaillent à le résoudre. La réponse retournée devraient contenir une entête X-Sentry-ID contenant un UUID identifiant votre requête. Le contenu de cette entête pourrait vous être demandé par notre équipe de support.

Localisation¶

Le contenu de certaines ressources est localisé via negotiation de contenu à partir de l’entête Accept-Language.

Par exemple, la ressource GET /api/v1/regions retournera un name localisé si une locale est spécifiée via l’entête mentionné précédemment.

Note

Si l’entête Accept-Language n’est pas fournie la locale du contenu sera déterminée à partir de la langue associé à l’utilisateur authentifié.

Ressources¶

Listes et abonnés¶

Listes¶

GET /api/v1/lists¶

Liste des listes d’abonnés existantes.

Response JSON Array of Objects:

id (int) – l’identifiant unique de la liste
create_datetime (datetime) – le datetime de création de la liste
create_user (int) – l’identifiant unique du créateur de la liste
update_datetime (datetime) – le datetime de dernière modification de la liste
update_user (int) – l’identifiant unique de l’utilisateur ayant fait la dernière modification à a liste
name (string) – le nom de la liste
default_from_name (string) – le nom d’expéditeur par défaut des envois futurs à cette liste
default_from_email (email) – l’adresse d’expédition par défaut des envois futurs à cette liste
default_replyto_email (email) – l’adresse de retour par défaut des envois futurs à cette liste
default_language (string) – la langue par défaut de la liste
languages (array) – les langues permise par la liste

Requête:

GET /api/v1/lists HTTP/1.1
Host: account.emailicious.com
Accept: application/json

Réponse:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "create_datetime": "2014-01-09T13:51:11.516441Z",
            "create_user": 1,
            "update_datetime": "2014-01-09T13:51:11.516481Z",
            "update_user": 1,
            "name": "Default",
            "default_from_name": "Emailicious",
            "default_from_email": "noreply@emailicious.com",
            "default_replyto_email": "info@emailicious.com",
            "default_language": "en",
            "languages": [
                "en",
                "fr"
            ]
        }
    ]
}

POST /api/v1/lists¶

Crée une nouvelle liste d’abonnés.

Request JSON Object:
	name (string) – le nom de la liste default_from_name (string) – le nom d’expéditeur par défaut des envois futurs à cette liste default_from_email (email) – l’adresse d’expédition par défaut des envois futurs à cette liste default_replyto_email (email) – l’adresse de retour par défaut des envois futurs à cette liste default_language (string) – la langue par défaut de la liste languages (array) – les langues permise par la liste
Response JSON Object:
	id (int) – l’identifiant unique de la liste create_datetime (datetime) – le datetime de création de la liste create_user (int) – l’identifiant unique du créateur de la liste update_datetime (datetime) – le datetime de dernière modification de la liste update_user (int) – l’identifiant unique de l’utilisateur ayant fait la dernière modification à a liste name (string) – le nom de la liste default_from_name (string) – le nom d’expéditeur par défaut des envois futurs à cette liste default_from_email (email) – l’adresse d’expédition par défaut des envois futurs à cette liste default_replyto_email (email) – l’adresse de retour par défaut des envois futurs à cette liste default_language (string) – la langue par défaut de la liste languages (array) – les langues permise par la liste
Status Codes:	201 Created – liste crée 400 Bad Request – données de liste d’abonnés invalides

Requête:

POST /api/v1/lists HTTP/1.1
Host: account.emailicious.com
Accept: application/json
Content-Type: application/json

{
    "name": "Default",
    "default_from_name": "Emailicious",
    "default_from_email": "noreply@emailicious.com",
    "default_replyto_email": "info@emailicious.com",
    "default_language": "en",
    "languages": [
        "en",
        "fr"
    ]
}

Réponse:

HTTP/1.1 201 CREATED
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

{
    "id": 1,
    "create_datetime": "2013-02-26T17:10:21.150Z",
    "create_user": 1,
    "update_datetime": "2013-02-26T17:10:21.150Z",
    "update_user": 1,
    "name": "Default",
    "default_from_name": "Emailicious",
    "default_from_email": "noreply@emailicious.com",
    "default_replyto_email": "info@emailicious.com",
    "default_language": "en",
    "languages": [
        "en",
        "fr"
    ]
}

GET /api/v1/lists/(int: id)¶

Détails de la liste d’abonnés correspondant au id spécifié.

Parameters:

id (int) – l’identifiant unique de la liste

Response JSON Object:

id (int) – l’identifiant unique de la liste
create_datetime (datetime) – le datetime de création de la liste
create_user (int) – l’identifiant unique du créateur de la liste
update_datetime (datetime) – le datetime de dernière modification de la liste
update_user (int) – l’identifiant unique de l’utilisateur ayant fait la dernière modification à a liste
name (string) – le nom de la liste
default_from_name (string) – le nom d’expéditeur par défaut des envois futurs à cette liste
default_from_email (email) – l’adresse d’expédition par défaut des envois futurs à cette liste
default_replyto_email (email) – l’adresse de retour par défaut des envois futurs à cette liste
default_language (string) – la langue par défaut de la liste
languages (array) – les langues permise par la liste

Requête:

GET /api/v1/lists/1 HTTP/1.1
Host: account.emailicious.com
Accept: application/json

Réponse:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
Content-Type: application/json

{
    "id": 1,
    "create_datetime": "2014-01-09T13:51:11.516441Z",
    "create_user": 1,
    "update_datetime": "2014-01-09T13:51:11.516481Z",
    "update_user": 1,
    "name": "Default",
    "default_from_name": "Emailicious",
    "default_from_email": "noreply@emailicious.com",
    "default_replyto_email": "info@emailicious.com",
    "default_language": "en",
    "languages": [
        "en",
        "fr"
    ]
}

Status Codes:	404 Not Found – aucune liste d’abonnés ne correspond au `id` spécifié

PUT /api/v1/lists/(int: id)¶

Modification de la liste d’abonnés correspondant au id spécifié.

Request JSON Object:
Parameters:	id (int) – l’identifiant unique de la liste
	name (string) – le nom de la liste default_from_name (string) – le nom d’expéditeur par défaut des envois futurs à cette liste default_from_email (email) – l’adresse d’expédition par défaut des envois futurs à cette liste default_replyto_email (email) – l’adresse de retour par défaut des envois futurs à cette liste default_language (string) – la langue par défaut de la liste languages (array) – les langues permise par la liste
Response JSON Object:
	id (int) – l’identifiant unique de la liste create_datetime (datetime) – le datetime de création de la liste create_user (int) – l’identifiant unique du créateur de la liste update_datetime (datetime) – le datetime de dernière modification de la liste update_user (int) – l’identifiant unique de l’utilisateur ayant fait la dernière modification à a liste name (string) – le nom de la liste default_from_name (string) – le nom d’expéditeur par défaut des envois futurs à cette liste default_from_email (email) – l’adresse d’expédition par défaut des envois futurs à cette liste default_replyto_email (email) – l’adresse de retour par défaut des envois futurs à cette liste default_language (string) – la langue par défaut de la liste languages (array) – les langues permise par la liste

Requête:

PUT /api/v1/lists/1 HTTP/1.1
Host: account.emailicious.com
Accept: application/json
Content-Type: application/json

{
    "name": "Altered name",
    "default_from_name": "Emailicious",
    "default_from_email": "noreply@emailicious.com",
    "default_replyto_email": "info@emailicious.com",
    "default_language": "en",
    "languages": [
        "en",
    ]
}

Réponse:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
Content-Type: application/json

{
    "id": 1,
    "create_datetime": "2014-01-09T13:51:11.516441Z",
    "create_user": 1,
    "update_datetime": "2015-01-09T13:51:11.516481Z",
    "update_user": 1,
    "name": "Altered name",
    "default_from_name": "Emailicious",
    "default_from_email": "noreply@emailicious.com",
    "default_replyto_email": "info@emailicious.com",
    "default_language": "en",
    "languages": [
        "en",
    ]
}

Status Codes:	400 Bad Request – données de liste d’abonnés invalides 404 Not Found – aucune liste d’abonnés ne correspond au `id` spécifié

PATCH /api/v1/lists/(int: id)¶

Modification partielle de la liste d’abonnés correspondant au id spécifié.

Request JSON Object:
Parameters:	id (int) – l’identifiant unique de la liste
	name (string) – le nom de la liste default_from_name (string) – le nom d’expéditeur par défaut des envois futurs à cette liste default_from_email (email) – l’adresse d’expédition par défaut des envois futurs à cette liste default_replyto_email (email) – l’adresse de retour par défaut des envois futurs à cette liste default_language (string) – la langue par défaut de la liste languages (array) – les langues permise par la liste
Response JSON Object:
	id (int) – l’identifiant unique de la liste create_datetime (datetime) – le datetime de création de la liste create_user (int) – l’identifiant unique du créateur de la liste update_datetime (datetime) – le datetime de dernière modification de la liste update_user (int) – l’identifiant unique de l’utilisateur ayant fait la dernière modification à a liste name (string) – le nom de la liste default_from_name (string) – le nom d’expéditeur par défaut des envois futurs à cette liste default_from_email (email) – l’adresse d’expédition par défaut des envois futurs à cette liste default_replyto_email (email) – l’adresse de retour par défaut des envois futurs à cette liste default_language (string) – la langue par défaut de la liste languages (array) – les langues permise par la liste

Requête:

PATCH /api/v1/lists/1 HTTP/1.1
Host: account.emailicious.com
Accept: application/json
Content-Type: application/json

{
    "default_from_name": "From emailicious",
}

Réponse:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH
Content-Type: application/json

{
    "id": 1,
    "create_datetime": "2014-01-09T13:51:11.516441Z",
    "create_user": 1,
    "update_datetime": "2015-01-09T13:51:11.516481Z",
    "update_user": 1,
    "name": "Default",
    "default_from_name": "From emailicious",
    "default_from_email": "noreply@emailicious.com",
    "default_replyto_email": "info@emailicious.com",
    "default_language": "en",
    "languages": [
        "en",
        "fr"
    ]
}

Status Codes:	400 Bad Request – données de liste d’abonnés invalides 404 Not Found – aucune liste d’abonnés ne correspond au `id` spécifié

DELETE /api/v1/lists/(int: id)¶

Suppression de la liste d’abonnés correspondant au id spécifié.

Parameters:	id (int) – l’identifiant unique de la liste

Avertissement

La suppression d’une liste entraînera inévitablement la suppression irréversible des envois et statistiques associés.

Requête:

DELETE /api/v1/lists/1 HTTP/1.1
Host: account.emailicious.com
Accept: application/json

Réponse:

HTTP/1.1 204 NO CONTENT
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH

Status Codes:	204 No Content – la liste d’abonnés à été supprimée avec succés 404 Not Found – aucune liste d’abonnés ne correspond au `id` spécifié

Abonnés¶

GET /api/v1/lists/(int: list_id)/subscribers¶

Abonnés de la liste correspondant au list_id spécifié.

Query Parameters:
Parameters:	list_id (int) – l’identifiant unique de la liste
	subscription – filtrer les résultats par statut d’abonnement, les valeurs valides sont `active`, `pending`, `bounced`, `unsubscribed` and `deleted` email – filtrer les résultats par `email`
Response JSON Array of Objects:
	id (int) – l’identifiant unique de la liste create_datetime (datetime) – le datetime de création de l’abonné create_user (int) – l’identifiant unique du créateur‘s de l’abonné update_datetime (datetime) – le datetime de dernière modification de l’abonné update_user (int) – L’identifiant unique de l’utilisateur ayant fait la dernière modification à l’abonné subscription (string) – statut d’abonnement de l’abonné email (email) – l’adresse courriel de l’abonné first_name (string) – prénom de l’abonné last_name (string) – nom de l’abonné gender (string) – sexe de l’abonné date_of_birth (date) – date de naissance de l’abonné language (string) – langue de l’abonné region (string) – région de l’abonné

Note

Les champs personnalisés partagés et de listes devraient aussi être présent dans les abonnés retournés. La structure exacte de la liste peut être retrouvée par introspection de la ressource.

Requête:

GET /api/v1/lists/1/subscribers HTTP/1.1
Host: account.emailicious.com
Accept: application/json

Réponse:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

{
    "count": 3,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "create_datetime": "2014-01-09T13:51:50.549536Z",
            "create_user": 1,
            "update_datetime": "2015-10-08T12:32:59.330455Z",
            "update_user": 1,
            "subscription": "active",
            "email": "active@example.com",
            "first_name": "Sergio",
            "last_name": "Leone",
            "gender": "m",
            "date_of_birth": "1929-01-03",
            "language": "it",
            "region": "IT-RM"
        },
        {
            "id": 2,
            "create_datetime": "2014-01-09T13:51:50.549536Z",
            "create_user": 1,
            "update_datetime": "2015-10-08T12:32:59.330455Z",
            "update_user": 1,
            "subscription": "bounced",
            "email": "bounced@example.com",
            "first_name": "Ennio",
            "last_name": "Morricone",
            "gender": "m",
            "date_of_birth": "1928-11-10",
            "language": "it",
            "region": "IT-RM"
        },
        {
            "id": 3,
            "create_datetime": "2014-01-09T13:51:50.549536Z",
            "create_user": 1,
            "update_datetime": "2015-10-08T12:32:59.330455Z",
            "update_user": 1,
            "subscription": "deleted",
            "email": "deleted@example.com",
            "first_name": "Clint",
            "last_name": "Eastwood",
            "gender": "m",
            "date_of_birth": "1930-05-31",
            "language": "en",
            "region": "US-CA"
        }
    ]
}

Status Codes:	404 Not Found – aucune liste d’abonnés ne correspond au `list_id` spécifié

POST /api/v1/lists/(int: list_id)/subscribers¶

Crée un abonné à la liste correspondant au list_id spécifié.

Request JSON Object:
Parameters:	list_id (int) – l’identifiant unique de la liste
	email (email) – l’adresse courriel de l’abonné first_name (string) – prénom de l’abonné last_name (string) – nom de l’abonné gender (string) – sexe de l’abonné date_of_birth (date) – date de naissance de l’abonné language (string) – langue de l’abonné region (string) – région de l’abonné

Note

Les champs personnalisés partagés et de listes peuvent aussi être spécificiés comme paramètres. La structure exacte de la liste peut être retrouvée par introspection de la ressource.

Response JSON Object:

id (int) – l’identifiant unique de la liste
create_datetime (datetime) – le datetime de création de l’abonné
create_user (int) – l’identifiant unique du créateur‘s de l’abonné
update_datetime (datetime) – le datetime de dernière modification de l’abonné
update_user (int) – L’identifiant unique de l’utilisateur ayant fait la dernière modification à l’abonné
subscription (string) – statut d’abonnement de l’abonné
email (email) – l’adresse courriel de l’abonné
first_name (string) – prénom de l’abonné
last_name (string) – nom de l’abonné
gender (string) – sexe de l’abonné
date_of_birth (date) – date de naissance de l’abonné
language (string) – langue de l’abonné
region (string) – région de l’abonné

Requête:

POST /api/v1/lists/1/subscribers HTTP/1.1
Host: account.emailicious.com
Accept: application/json
Content-Type: application/json

{
    "email": "test@example.com",
    "first_name": "Dolly",
    "last_name": "Parton",
    "gender": "f",
    "date_of_birth": "1946-01-19",
    "language": "en",
    "region": "US-TN"
}

Réponse:

HTTP/1.1 201 CREATED
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

{
    "id": 1,
    "create_datetime": "2015-11-27T22:14:36.590658Z",
    "create_user": 1,
    "update_datetime": "2015-11-27T22:14:36.590711Z",
    "update_user": 1,
    "subscription": "active",
    "email": "test@example.com",
    "first_name": "Dolly",
    "last_name": "Parton",
    "gender": "f",
    "date_of_birth": "1946-01-19",
    "language": "en",
    "region": "US-TN"
}

Status Codes:	201 Created – l’abonné a été créé avec succès 400 Bad Request – données d’abonné invalides 404 Not Found – aucune liste d’abonnés ne correspond au `list_id` spécifié 409 Conflict – un abonné avec l’adresse courriel spécifée existe déjà dans cette liste.

Gérer les erreurs 409 Conflict

Lorsqu’une tentative de création ou de modification d’un abonné entraîne une collision du champ adresse courriel l’abonné conflictuel est retourné dans le corps d’une réponse 409 Conflict.

HTTP/1.1 409 CONFLICT
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

{
    "id": 2,
    "create_datetime": "2015-11-27T22:14:36.590658Z",
    "create_user": 1,
    "update_datetime": "2015-11-27T22:14:36.590711Z",
    "update_user": 1,
    "subscription": "active",
    "email": "conflict@example.com",
    "first_name": "Dolly",
    "last_name": "Parton",
    "gender": "f",
    "date_of_birth": "1946-01-19",
    "language": "en",
    "region": "US-TN"
}

Lorsqu’un tel conflit se produit votre application se doit d’informer l’utilisateur à la source de la requête que ce email est déjà abonné à la liste de diffusion ou bien procéder à la mise à jour de l’abonné conflictuel si l’utilisateur à préalablement prouvé qu’il était bien le propriétaire de l’adresse en question.

Notez qu’un tel conflit peut également se produire lorsqu’un abonné s’est préalablement désinscrit ou a été supprimé d’une liste. La marche à suivre dans ces cas dépend entièrement de votre logique applicative. Par exemple, vous pourriez vouloir confirmer le réabonnement ou bien simplement ignorer telles exceptions.

OPTIONS /api/v1/lists/(int: list_id)/subscribers¶

Détails introspectif de la ressource « abonnés ».

Parameters:	list_id (int) – l’identifiant unique de la liste

Requête:

OPTIONS /api/v1/lists/1/subscribers HTTP/1.1
Host: account.emailicious.com
Accept: application/json

Réponse:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

{
    "name": "Subscriber List",
    "renders": [
        "application/json",
        "text/html"
    ],
    "parses": [
        "application/json",
        "application/x-www-form-urlencoded",
        "multipart/form-data"
    ],
    "actions": {
        "POST": {
            "id": {
                "type": "integer",
                "required": false,
                "read_only": true,
                "label": "ID"
            },
            "create_datetime": {
                "type": "datetime",
                "required": false,
                "read_only": true,
                "label": "Create datetime"
            },
            "create_user": {
                "type": "field",
                "required": false,
                "read_only": true,
                "label": "Create user"
            },
            "update_datetime": {
                "type": "datetime",
                "required": false,
                "read_only": true,
                "label": "Update datetime"
            },
            "update_user": {
                "type": "field",
                "required": false,
                "read_only": true,
                "label": "Update user"
            },
            "subscription": {
                "type": "field",
                "required": false,
                "read_only": true,
                "label": "Subscription"
            },
            "email": {
                "type": "email",
                "required": true,
                "read_only": false,
                "label": "Email",
                "max_length": 254
            },
            "first_name": {
                "type": "string",
                "required": false,
                "read_only": false,
                "label": "First name",
                "max_length": 100
            },
            "last_name": {
                "type": "string",
                "required": false,
                "read_only": false,
                "label": "Last name",
                "max_length": 100
            },
            "gender": {
                "type": "choice",
                "required": false,
                "read_only": false,
                "label": "Gender",
                "choices": [
                    {
                        "display_name": "Unknown",
                        "value": ""
                    },
                    {
                        "display_name": "Male",
                        "value": "m"
                    },
                    {
                        "display_name": "Female",
                        "value": "f"
                    }
                ]
            },
            "date_of_birth": {
                "type": "date",
                "required": false,
                "read_only": false,
                "label": "Date of birth"
            },
            "language": {
                "type": "field",
                "required": false,
                "read_only": false,
                "label": "Language",
                "help_text": "ISO-639-1 language code."
            },
            "region": {
                "type": "field",
                "required": false,
                "read_only": false,
                "label": "Region",
                "help_text": "ISO-3166-1 country or ISO-3166-2 region code."
            }
        }
    }
}

Introspection des champs personnalisés

Vous pouvez retrouver le nom et type des champs personnalisés de la liste spécifié à partir de la section actions.POST de la réponse.

Status Codes:	404 Not Found – aucune liste d’abonnés ne correspond au `list_id` spécifié

GET /api/v1/lists/(int: list_id)/subscribers/(int: id)¶

Détails de l’abonné correspondant aux list_id et id spécifiés.

Parameters:

list_id (int) – l’identifiant unique de la liste
id (int) – l’identifiant unique de la liste

Response JSON Object:

id (int) – l’identifiant unique de la liste
create_datetime (datetime) – le datetime de création de l’abonné
create_user (int) – l’identifiant unique du créateur‘s de l’abonné
update_datetime (datetime) – le datetime de dernière modification de l’abonné
update_user (int) – L’identifiant unique de l’utilisateur ayant fait la dernière modification à l’abonné
subscription (string) – statut d’abonnement de l’abonné
email (email) – l’adresse courriel de l’abonné
first_name (string) – prénom de l’abonné
last_name (string) – nom de l’abonné
gender (string) – sexe de l’abonné
date_of_birth (date) – date de naissance de l’abonné
language (string) – langue de l’abonné
region (string) – région de l’abonné

Note

Les champs personnalisés partagés et de listes devraient aussi être présent dans l’abonné retourné. La structure exacte de la liste peut être retrouvée en introspectant la ressource.

Requête:

GET /api/v1/lists/1/subscribers/1 HTTP/1.1
Host: account.emailicious.com
Accept: application/json

Réponse:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

{
    "id": 1,
    "create_datetime": "2015-11-27T22:14:36.590658Z",
    "create_user": 1,
    "update_datetime": "2015-11-28T22:14:36.590711Z",
    "update_user": 1,
    "subscription": "active",
    "email": "test@example.com",
    "first_name": "Dolly",
    "last_name": "Parton",
    "gender": "f",
    "date_of_birth": "1946-01-19",
    "language": "en",
    "region": "US-TN"
}

Status Codes:	404 Not Found – aucun abonné ne correspond aux `list_id` et `id` spécifiés.

PUT /api/v1/lists/(int: list_id)/subscribers/(int: id)¶

Modifie l’abonné correspondant aux list_id et id spécifiés.

Request JSON Object:
Parameters:	list_id (int) – l’identifiant unique de la liste id (int) – l’identifiant unique de la liste
	email (email) – l’adresse courriel de l’abonné first_name (string) – prénom de l’abonné last_name (string) – nom de l’abonné gender (string) – sexe de l’abonné date_of_birth (date) – date de naissance de l’abonné language (string) – langue de l’abonné region (string) – région de l’abonné

Note

Les champs personnalisés partagés et de listes peuvent aussi être spécificiés comme paramètres. La structure exacte de la liste peut être retrouvée par introspection de la ressource.

Response JSON Object:

id (int) – l’identifiant unique de la liste
create_datetime (datetime) – le datetime de création de l’abonné
create_user (int) – l’identifiant unique du créateur‘s de l’abonné
update_datetime (datetime) – le datetime de dernière modification de l’abonné
update_user (int) – L’identifiant unique de l’utilisateur ayant fait la dernière modification à l’abonné
subscription (string) – statut d’abonnement de l’abonné
email (email) – l’adresse courriel de l’abonné
first_name (string) – prénom de l’abonné
last_name (string) – nom de l’abonné
gender (string) – sexe de l’abonné
date_of_birth (date) – date de naissance de l’abonné
language (string) – langue de l’abonné
region (string) – région de l’abonné

Requête:

POST /api/v1/lists/1/subscribers/1 HTTP/1.1
Host: account.emailicious.com
Accept: application/json
Content-Type: application/json

{
    "email": "test@example.com",
    "first_name": "Altered Dolly",
    "last_name": "Parton",
    "gender": "f",
    "date_of_birth": "1946-01-19",
    "language": "en",
    "region": "US-TN"
}

Réponse:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

{
    "id": 1,
    "create_datetime": "2015-11-27T22:14:36.590658Z",
    "create_user": 1,
    "update_datetime": "2015-11-28T22:14:36.590711Z",
    "update_user": 1,
    "subscription": "active",
    "email": "test@example.com",
    "first_name": "Altered Dolly",
    "last_name": "Parton",
    "gender": "f",
    "date_of_birth": "1946-01-19",
    "language": "en",
    "region": "US-TN"
}

Status Codes:	400 Bad Request – données d’abonné invalides 404 Not Found – aucun abonné ne correspond aux `list_id` et `id` spécifiés. 409 Conflict – un abonné avec l’adresse courriel spécifée existe déjà dans cette liste.

PATCH /api/v1/lists/(int: list_id)/subscribers/(int: id)¶

Modification partielle de l’abonné correspondat aux list_id et id spécifiés.

Request JSON Object:
Parameters:	list_id (int) – l’identifiant unique de la liste id (int) – l’identifiant unique de la liste
	email (email) – l’adresse courriel de l’abonné first_name (string) – prénom de l’abonné last_name (string) – nom de l’abonné gender (string) – sexe de l’abonné date_of_birth (date) – date de naissance de l’abonné language (string) – langue de l’abonné region (string) – région de l’abonné

Note

Les champs personnalisés partagés et de listes peuvent aussi être spécificiés comme paramètres. La structure exacte de la liste peut être retrouvée par introspection de la ressource.

Response JSON Object:

id (int) – l’identifiant unique de la liste
create_datetime (datetime) – le datetime de création de l’abonné
create_user (int) – l’identifiant unique du créateur‘s de l’abonné
update_datetime (datetime) – le datetime de dernière modification de l’abonné
update_user (int) – L’identifiant unique de l’utilisateur ayant fait la dernière modification à l’abonné
subscription (string) – statut d’abonnement de l’abonné
email (email) – l’adresse courriel de l’abonné
first_name (string) – prénom de l’abonné
last_name (string) – nom de l’abonné
gender (string) – sexe de l’abonné
date_of_birth (date) – date de naissance de l’abonné
language (string) – langue de l’abonné
region (string) – région de l’abonné

Requête:

PATH /api/v1/lists/1/subscribers/1 HTTP/1.1
Host: account.emailicious.com
Accept: application/json
Content-Type: application/json

{
    "first_name": "Altered Dolly",
}

Réponse:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, PUT, PATCH, DELETE, HEAD, OPTIONS
Content-Type: application/json

{
    "id": 1,
    "create_datetime": "2015-11-27T22:14:36.590658Z",
    "create_user": 1,
    "update_datetime": "2015-11-28T22:14:36.590711Z",
    "update_user": 1,
    "subscription": "active",
    "email": "test@example.com",
    "first_name": "Altered Dolly",
    "last_name": "Parton",
    "gender": "f",
    "date_of_birth": "1946-01-19",
    "language": "en",
    "region": "US-TN"
}

Status Codes:	400 Bad Request – données d’abonné invalides 404 Not Found – aucun abonné ne correspond aux `list_id` et `id` spécifiés. 409 Conflict – un abonné avec l’adresse courriel spécifée existe déjà dans cette liste.

DELETE /api/v1/lists/(int: list_id)/subscribers/(int: id)¶

Assigne le statut d’abonnement deleted à l’abonné correspondant aux list_id et id spécifiés

Parameters:	list_id (int) – l’identifiant unique de la liste id (int) – l’identifiant unique de la liste

Requête:

DELETE /api/v1/lists/1/subscribers/1 HTTP/1.1
Host: account.emailicious.com
Accept: application/json

Réponse:

HTTP/1.1 204 NO CONTENT
Vary: Accept
Allow: GET, PUT, DELETE, HEAD, OPTIONS, PATCH

Status Codes:	204 No Content – le statut d’abonnement de l’abonné à été modifié avec succès 404 Not Found – aucun abonné ne correspond aux `list_id` et `id` spécifiés.

POST /api/v1/lists/(int: list_id)/subscribers/(int: id)/activate¶

Assigne le statut d’abonnement pending ou active à l’abonné correspondant aux list_id et id spécifiés en fonction du processus d’adhésion de la liste ainsi que la valeur du paramètre confirm.

Request JSON Object:
Parameters:	list_id (int) – l’identifiant unique de la liste id (int) – l’identifiant unique de la liste
	confirm (boolean) – outrepasse le processus d’adhésion configuré
Response JSON Object:
	status (string) – le statut d’abonnement de l’abonné

POST /api/v1/lists/1/subscribers/1/activate HTTP/1.1
Host: account.emailicious.com
Accept: application/json

HTTP/1.1 200 OK
Vary: Accept
Allow: POST, OPTIONS
Content-Type: application/json

{
    "status": "active"
}

Status Codes:	400 Bad Request – il n’est pas possible de confirmer l’abonnement à la liste puisqu’aucun processus n’est configuré 404 Not Found – aucun abonné ne correspond aux `list_id` et `id` spécifiés.

POST /api/v1/lists/(int: list_id)/subscribers/(int: id)/unsubscribe¶

Assigne le statut d’abonnement unsubscribed à l’abonné correspondant aux list_id et id spécifiés

Response JSON Object:
Parameters:	list_id (int) – l’identifiant unique de la liste id (int) – l’identifiant unique de la liste
	status (string) – le statut d’abonnement de l’abonné

POST /api/v1/lists/1/subscribers/1/unsubscribe HTTP/1.1
Host: account.emailicious.com
Accept: application/json

HTTP/1.1 200 OK
Vary: Accept
Allow: POST, OPTIONS
Content-Type: application/json

{
    "status": "unsubscribed"
}

Status Codes:	404 Not Found – aucun abonné ne correspond aux `list_id` et `id` spécifiés.

Importations¶

POST /api/v1/lists/(int: list_id)/imports¶

Importe le fichier CSV téléversé en tant qu’abonnés à la liste spécifiée.

Parameters:

list_id (int) – l’identifiant unique de la liste

Form Parameters:

file – le fichier CSV contenant les abonnés
encoding – l’encodage du fichier, s’il n’est pas spécifié il sera détecté automatiquement
delimiter – le délimiteur de colonnes, s’il n’est pas spécifié il sera détecté automatiquement
has_header – signale la présence ou l’absence d’un entête, la présence sera détectée automatiquement si le paramètre n’est pas spécifié
ignore_invalid_fields – détermine la manière dont les colonnes contenant des données invalides doivent être traitées
date_format – le format strptime utilisé pour représenter les dates
fields – association des index de colonnes du fichier aux champs des abonnés

Si le paramètre fields n’est pas fourni vous devez assigner la valeur true au paramètre has_header afin que la première ligne du fichier soit considérée comme l’entête associant les colonnes aux champs des abonnés.

subscribers.csv¶
email	first_name	gender	language
alice@domain.com	Alice	f	fr
bob@example.com	Bob	m	en

Requête:

POST /api/v1/lists/1/imports HTTP/1.1
Host: account.emailicious.com
Accept: application/json
Content-Type: multipart/form-data; boundary=------------------------aefc77a7a0e120e9

Réponse:

HTTP/1.1 201 CREATED
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

{
    "id": 1,
    "file": "subscribers.csv",
    "encoding": "utf-8",
    "delimiter": ",",
    "has_header": true,
    "ignore_invalid_fields": true,
    "date_format": "%d-%m-%Y",
    "fields": [
        "email",
        "first_name",
        "gender",
        "language"
    ]
}

Status Codes:	201 Created – l’importation a été crée avec succès 400 Bad Request – données d’importation invalides 404 Not Found – aucune liste d’abonnés ne correspond au `list_id` spécifié

Envois¶

GET /api/v1/mailings¶

Liste des envois existants

Query Parameters:
	list – filtre les résultats par identifiant unique de liste
Response JSON Array of Objects:
	id (int) – l’identifiant unique de l’envoi name (string) – le nom unique de l’envoi campaign (int) – l’identifiant unique de la campagne de cet envoi

Requête:

GET /api/v1/mailings HTTP/1.1
Host: account.emailicious.com
Accept: application/json

Réponse:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json

{
    "count": 3,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "name": "First mailing",
            "campaign": null
        },
        {
            "id": 2,
            "name": "Mailing with campaign",
            "campaign": 1
        },
        {
            "id": 3,
            "name": "Third mailing",
            "campaign": null
        }
    ]
}

POST /api/v1/mailings¶

Crée un envoi avec possiblité de variantes et livraisons multiples.

Request JSON Object:

list (int) – l’identifiant unique de la liste
name (string) – le nom unique de l’envoi
campaign (int) – l’identifiant unique de la campagne
segments (array) – identifiants uniques des segments
variants (array) – variantes
variants.language (array) – code de langue de la variante
variants.from_name (string) – nom de l’expéditeur de la variante (prend la valeur default_from_name de la liste si définit)
variants.from_email (string) – nom de l’expéditeur de la variante (prend la valeur default_from_email de la liste si définit)
variants.replyto_email (string) – nom de l’expéditeur de la variante (prend la valeur default_replyto_email de la liste si définit)
variants.subject (string) – object de la variante
variants.layout.text (string) – contenu texte de la variante
variants.layout.zip_file (string) – fichier Zip sous forme de data URI représentant le contenu HTML de la variante
variants.deliveries (array) – livraisons
variants.deliveries.scheduled_datetime (string) – date et temps de la livraison

Note

Afin de permettre la soumission de fichiers lors des requêtes dont le Content-Type est application/json leur contenu doit être sous forme de data URI.

Les champs variants.layout.zip_file doivent être des fichiers Zip contenant l’aborescence suivante.

Un fichier index.html représentant la mise en page HTML du gabarit.
Et optionnelement des fichiers images (.jpg, .png, .gif) placéesdans un dossier images accessible depuis la racine de l’archive. Ces images devront être référencées de manière relative depuis le fichier index.html afin d’être considérées lors de l’importation du gabarit.

Voici un exemple Python démontrant comment générer une archive de valide compatible:

import StringIO
import zipfile

html = """<!DOCTYPE html>
<html>
    <body>
        Hello World!
        <img src="images/planet.png" />
    </body>
</html>"""

buffer = StringIO.StringIO()
with zipfile.ZipFile(buffer, mode='w') as archive:
    archive.writestr('index.html', html)
    archive.write('/path/to/planet.png', 'images/planet.png')

# URI encode the Zip file.
layout = 'data:application/zip;charset=utf-8;base64,%s' % (
    buffer.getvalue().encode('base64'),
)

Requête:

POST /api/v1/mailings HTTP/1.1
Host: account.emailicious.com
Accept: application/json
Content-Type: application/json

{
    "list": 1,
    "name": "Mailing",
    "variants": [
        {
            "subject": "Hello World!",
            "layout": {
                "zip_file": "data:application/zip;charset=utf-8;base64,..."
            },
            "deliveries": [
                {
                    "scheduled_datetime": "2017-05-15T19:30:33Z"
                }
            ]
        }
    ]
}

Réponse:

HTTP/1.1 201 Created
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "id": 1,
    "name": "Mailing",
    "list": 1,
    "campaign": null,
    "segments": [],
    "variants": [
        {
            "from_name": "List default from name",
            "from_email": "list@default.from.email",
            "replyto_email": "",
            "subject": "Hello World!",
            "deliveries": [
                {
                    "exclusions": [],
                    "limit": null,
                    "scheduled_datetime": "2017-05-15T19:30:33Z"
                }
            ],
            "language": null,
            "layout": {
                "id": 1,
                "source": "<!DOCTYPE html>\n<html>\n<body>...</body>\n</html>"
            }
        }
    ]
}

Statistiques¶

GET /api/v1/statistics/opens¶

Statistiques d’ouvertures

Query Parameters:
	campaign (int) – filtrer les résultats par identifiant unique de campagne mailing (int) – filtre les résultats par identifiant unique d’envoi unique (boolean) – agrège les ouvertures par envoi date (date) – filtrer les résultats par date from_datetime (datetime) – filtrer les résultats dont le `datetime` est plus récent to_datetime (datetime) – filtrer les résultats dont le `datetime` est moins récent
Response JSON Object:
	mailing (int) – l’envoi à l’origine de l’ouverture email (email) – le courriel du destinataire ayant ouvert datetime (datetime) – le `datetime` de l’ouverture

Requête:

GET /api/v1/statistics/opens HTTP/1.1
Host: account.emailicious.com
Accept: application/json

Réponse:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "mailing": 1,
            "email": "foo@bar.org",
            "datetime": "2014-06-06T20:56:57Z"
        }
    ]
}

GET /api/v1/statistics/clicks¶

Statistiques de clics

Query Parameters:
	campaign (int) – filtrer les résultats par identifiant unique de campagne mailing (int) – filtre les résultats par identifiant unique d’envoi unique (boolean) – agrège les clics par envoi date (date) – filtrer les résultats par date from_datetime (datetime) – filtrer les résultats dont le `datetime` est plus récent to_datetime (datetime) – filtrer les résultats dont le `datetime` est moins récent url (url) – filtre les résultats par l’URL du lien cliqué
Response JSON Object:
	mailing (int) – l’envoi à l’origine du clic email (email) – le courriel du destinataire ayant cliqué datetime (datetime) – le courriel du destinataire ayant ouvert url (url) – l’URL du lien cliqué

Requête:

GET /api/v1/statistics/clicks HTTP/1.1
Host: account.emailicious.com
Accept: application/json

Réponse:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "mailing": 1,
            "email": "foo@bar.org",
            "datetime": "2014-06-06T20:56:57Z",
            "url": "https://example.com"
        }
    ]
}

GET /api/v1/statistics/bounces¶

Statistiques de rebonds

Query Parameters:
	campaign (int) – filtrer les résultats par identifiant unique de campagne mailing (int) – filtre les résultats par identifiant unique d’envoi unique (boolean) – agrège les rebonds par envoi date (date) – filtrer les résultats par date from_datetime (datetime) – filtrer les résultats dont le `datetime` est plus récent to_datetime (datetime) – filtrer les résultats dont le `datetime` est moins récent hard (boolean) – filtrer les résultats par statut de permanence du rebond
Response JSON Object:
	mailing (int) – l’envoi à l’origine du rebond email (email) – le `datetime` du rebond datetime (datetime) – filtrer les résultats dont le `datetime` est moins récent hard (boolean) – le statut permanent du rebond

Requête:

GET /api/v1/statistics/bounces HTTP/1.1
Host: account.emailicious.com
Accept: application/json

Réponse:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "mailing": 1,
            "email": "foo@bar.org",
            "datetime": "2014-06-06T20:56:57Z",
            "hard": false
        }
    ]
}

Localisation¶

Langues¶

GET /api/v1/languages¶

Liste des codes de langues ISO-639-1 supportées.

Response JSON Array of Objects:
	code (string) – code ISO-639-1 de la langue name (string) – nom localisé de la langue

Requête:

GET /api/v1/languages HTTP/1.1
Host: account.emailicious.com
Accept: application/json

Réponse:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

{
    "count": 96,
    "next": "/api/v1/languages?page=2",
    "previous": null,
    "results": [
        {
            "code": "ab",
            "name": "Abkhazian"
        },
        {
            "code": "af",
            "name": "Afrikaans"
        },
        {
            "code": "an",
            "name": "Aragonese"
        },
        {
            "code": "ar",
            "name": "Arabic"
        }
    ]
}

Régions¶

GET /api/v1/regions¶

Liste des codes de pays ISO-3166-1 et subdivisions ISO-3166-2 supportés.

Query Parameters:
	code – filtre les résultats par `code` search – filtre les résultats par `name` et `name` de leur pays associé
Response JSON Array of Objects:
	code (string) – code ISO-3166 du pays ou de la subdivision name (string) – nom localisé du pays ou de la subdivision

Requête:

GET /api/v1/regions HTTP/1.1
Host: account.emailicious.com
Accept: application/json

Réponse:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

{
    "count": 5140,
    "next": "/api/v1/regions?page=2",
    "previous": null,
    "results": [
        {
            "code": "AD",
            "name": "Andorra"
        },
        {
            "code": "AD-02",
            "name": "Canillo"
        },
        {
            "code": "AD-03",
            "name": "Encamp"
        },
        {
            "code": "AD-04",
            "name": "La Massana"
        },
        {
            "code": "AD-05",
            "name": "Ordino"
        }
    ]
}

GET /api/v1/regions/(string: code)¶

Détails de la région correspondant au code spécifié.

Response JSON Object:
Parameters:	code (string) – Code de pays ou de subdivision ISO-3166.
	code (string) – code ISO-3166 du pays ou de la subdivision name (string) – nom localisé du pays ou de la subdivision country (string) – code ISO-3166-1 du pays de la subdivision regions (array) – codes ISO-3166-2 et noms localisés des subdivisions du pays

Requête:

GET /api/v1/regions/CA HTTP/1.1
Host: account.emailicious.com
Accept: application/json

Réponse:

HTTP/1.1 200 OK
Vary: Accept
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

{
    "code": "CA",
    "name": "Canada",
    "country": null,
    "regions": [
        {
            "code": "CA-AB",
            "name": "Alberta"
        },
        {
            "code": "CA-BC",
            "name": "British Columbia"
        },
        {
            "code": "CA-MB",
            "name": "Manitoba"
        },
        {
            "code": "CA-NB",
            "name": "New Brunswick"
        },
        {
            "code": "CA-NL",
            "name": "Newfoundland and Labrador"
        },
        {
            "code": "CA-NS",
            "name": "Nova Scotia"
        },
        {
            "code": "CA-NT",
            "name": "Northwest Territories"
        },
        {
            "code": "CA-NU",
            "name": "Nunavut"
        },
        {
            "code": "CA-ON",
            "name": "Ontario"
        },
        {
            "code": "CA-PE",
            "name": "Prince Edward Island"
        },
        {
            "code": "CA-QC",
            "name": "Quebec"
        },
        {
            "code": "CA-SK",
            "name": "Saskatchewan"
        },
        {
            "code": "CA-YT",
            "name": "Yukon Territory"
        }
    ]
}

Documentation de l’API d’Emailicious¶

Table des matières¶

Sujets¶

Introduction¶

Authentification¶

Erreurs¶

Erreurs client¶

400 Bad Request¶

401 Unauthorized¶

404 Not Found¶

409 Conflict¶

Erreurs serveur¶

500 Internal Server Error¶

Localisation¶

Ressources¶

Listes et abonnés¶

Listes¶

Abonnés¶

Importations¶

Envois¶

Envois¶

Statistiques¶

Statistiques¶

Localisation¶

Langues¶

Régions¶

400 Bad Request ¶

401 Unauthorized ¶

404 Not Found ¶

409 Conflict ¶

500 Internal Server Error ¶