NAV Navbar
cURL PHP

Introduction

Welcome to the MailKitchen API! You can use our API to access MailKitchen API endpoints, which can use features from platform MailKitchen.

We have language bindings in Shell, PHP! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

In order to use this API, you need to enable it in our platform portal in your account settings. You will retrieve two parameters which is necessary to get token for the use of API that looks like the following:

API KEY : <api_key>

API SECRET KEY : <api_secret_key>

Login

## API Endpoint
$ curl -X POST https://api.mailkitchen.com/v1/login 
    -H 'Content-Type: application/json'
    -d '{ "api_key": "<api_key>", "api_secret_key": "<api_secret_key>" }'


## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": {
        "token": "<token>"
    }
}

# token | This token allows you to authenticate for each API's call
<?php
require 'vendor/autoload.php';

CONST API_KEY = '<api_key>'; 
CONST API_SECRET_KEY = '<api_secret_key>'; 

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);
?>

MailKitchen uses API keys to allow access to the API and retrieve a token.

HTTP Request

POST https://api.mailkitchen.com/v1/login

Query Parameters

Parameter Required
api_key true
api_secret_key true

Authentication

## API Endpoint
curl '<api_endpoint>' 
    -H 'Authorization: Bearer <token>'

# Make sure to replace token parameter with your API Bearer token.
<?php
// The previous code to create a client object has token variable passed by default for each connection
?>

MailKitchen expects for the API Bearer Token to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer <token>

Contacts

MailKitchen API allows you to handle your contacts. Those contacts can be in mailing lists or unsubscribe lists and you can manage them inside those lists. To have more details for your contacts, custom fields may be too added.

Subscribers

## API Endpoint
$ curl -X GET https://api.mailkitchen.com/v1/subscribers/<email>
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": {
        "subscriber": {
            "id": "1378",
            "email": "[email protected]",
            "insertion_date": "2013-09-25 02:00:00",
            "hard_bounce": null,
            "soft_bounce": null,
            "count_soft_bounce": "0"
        },
        "mailing_list": [
            {
                "id": "39",
                "name": "test",
                "creation_date": "2013-09-25 02:00:00",
                "subscriber_count": "33"
            },
            {
                "id": "70",
                "name": "test2",
                "creation_date": "2013-09-25 02:00:00",
                "subscriber_count": "6"
            }
        ],
        "unsubscribe_list": [
            {
                "id": "2",
                "name": "List-Unsubscribe (default)",
                "subscriber_count": "9"
            }
        ]
    }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>'; 
CONST API_SECRET_KEY = '<api_secret_key>'; 

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->get(Resources::SUBSCRIBERS, "<email>");
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

A subscriber is a contact in a list to send a mail to it. This endpoint retrieves a specific subscriber.

HTTP Request

GET https://api.mailkitchen.com/v1/subscribers/<email>

Query Parameters

Parameter Required Description
email true Subscribers's email

Response

The response is formatted in JSON with the status of API's request, you will get a subscriber details with details and lists where subscibers is in.

Subscriber data
Field Description
id Subscriber's identifier in database
email Subscriber's email
insertion_date Subscriber's record date
hard_bounce A date when the subscriber's mailbox is definitively unreachable ('null' indicated the case).
soft_bounce A date when the subscriber's mailbox is temporarily unreachable ('null' indicated the case).
count_soft_bounce Number of attempt sent which the subscriber's mailbox is temporarily unreachable.
Mailing list data
Field Description
id Mailing list's identifier in database
name Mailing list's email
creation_date Mailing list's record date
subscriber_count Subscribers number in the mailing list.
Unsubscribe list data
Field Description
id Unsubscribe list's identifier in database
name Unsubscribe list's email
subscriber_count Subscribers number in the unsubscribe list.

Custom Fields

Custom fields are that you want associate with a subscriber to add some information for the subscriber.

Get all custom fields

## API Endpoint
$ curl -X GET https://api.mailkitchen.com/v1/customfields
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": [
        {
            "libelle": "collectiv_hebdo",
            "type": "int"
        },
        ...
        {
            "libelle": "prenom",
            "type": "varchar"
        }
    ]
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>'; 
CONST API_SECRET_KEY = '<api_secret_key>'; 

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->get(Resources::CUSTOM_FIELDS);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint retrieves all custom fields in your MailKitchen account.

HTTP Request

GET https://api.mailkitchen.com/v1/customfields

Response

The response is formatted in JSON with the status of API's request, you will get all custom fields.

Field Description
libelle Name of the custom field
type Type SQL of the custom field

Get all custom fields by sql type

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/customfields/<typeOfSqlCustomField>
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": [
        {
            "libelle": "collectiv_hebdo",
            "type": "<typeOfSqlCustomField>"
        },
        ...
    ]
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>'; 
CONST API_SECRET_KEY = '<api_secret_key>'; 

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->get(Resources::CUSTOM_FIELDS, "INTEGER");
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint retrieves all custom fields with a sql type field in your MailKitchen account.

HTTP Request

GET https://api.mailkitchen.com/v1/customfields/<sqlTypeOfCustomField>

Response

The response is formatted in JSON with the status of API's request, you will get all custom fields with a specific sql type field.

Field Description
libelle Name of the custom field
type Type SQL of the custom field you passed

Create a custom field

## API Endpoint
curl -X POST https://api.mailkitchen.com/v1/customfields
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'
    -d '{ "name": "<nameCustomField>", "sql_type": "<sqlTypeOfCustomField>" }'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 201,
        "http_message": "201 (Created)"
    },
    "data": {
        "name": "<nameCustomField>",
        "sql_type": "<sqlTypeOfCustomField>"
    }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>'; 
CONST API_SECRET_KEY = '<api_secret_key>'; 

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$customFieldsData = [
    'name' => '<nameCustomField>',
    'sql_type' => '<sqlTypeOfCustomField>'
];
$response = $mk->post(Resources::CUSTOM_FIELDS, null, $customFieldsData);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint allows you to create a custom field in your MailKitchen account.

HTTP Request

POST https://api.mailkitchen.com/v1/customfields

Query Parameters

Parameter Required Description
name true Name of the custom field
sql_type true The SQL type field of the custom field

Response

The response is formatted in JSON with the status of API's request. The custom field will be add.

Field Description
name Name of the custom field
sql_type The SQL type field of the custom field

Delete a custom field

## API Endpoint
curl -X DELETE https://api.mailkitchen.com/v1/customfields/<customField>
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": "Your custom field has been successfully deleted for: <customField>."
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>'; 
CONST API_SECRET_KEY = '<api_secret_key>'; 

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->delete(Resources::CUSTOM_FIELDS, "<customField>");
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint allows you to delete a custom field in your MailKitchen account.

HTTP Request

DELETE https://api.mailkitchen.com/v1/customfields/<customField>

Query Parameters

Parameter Required Description
name true Name of the custom field

Response

The response is formatted in JSON with the status of API's request. The custom field will be delete.

Mailing Lists

A mailing list allows you to define which contacts send your emails. For this, just include your subscribers. In this section, you can handle several mailing lists and its contents.

Get all mailing lists

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/mailinglists
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": [
        {
            "id": "39",
            "name": "test",
            "creation_date": "2016-10-16 17:14:10",
            "subscriber_count": "33"
        },
        ...
        {
            "id": "199",
            "name": "test11",
            "creation_date": "2019-10-16 17:14:10",
            "subscriber_count": "0"
        }
    ]
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>'; 
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->get(Resources::MAILING_LISTS);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint retrieves all mailing lists in your MailKitchen account.

HTTP Request

GET https://api.mailkitchen.com/v1/mailinglists

Response

The response is formatted in JSON with the status of API's request, you will get all mailing lists.

Field Description
id Mailing list's identifier in database
name Mailing list's name
creation_date Mailing list's record date
subscriber_count The number of subscribers in the mailing list

Get a mailing list

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/mailinglists/<idMailingList>
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": {
        "id": "201",
        "name": "testdic2",
        "creation_date": "2019-10-24 19:21:09",
        "subscribers_count": 0
    }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>'; 
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->get(Resources::MAILING_LISTS, "<idMailingList>");
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint retrieves a mailing list in your MailKitchen account.

HTTP Request

GET https://api.mailkitchen.com/v1/mailinglists/<idMailingList>

Response

The response is formatted in JSON with the status of API's request, you will get the mailing list detail.

Field Description
id Mailing list's identifier in database
name Mailing list's name
creation_date Mailing list's record date
subscriber_count The number of subscribers in the mailing list

Create a mailing list

## API Endpoint
curl -X POST https://api.mailkitchen.com/v1/mailinglists
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'
    -d '{ "name": "<nameMailingList>" }'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 201,
        "http_message": "201 (Created)"
    },
    "data": {
        "id": "201",
        "name": "testdic2",
        "creation_date": "2019-10-24 19:21:09",
        "subscribers_count": 0
    }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>'; 
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$mailingListData = ['name' => '<nameMailingList>'];
$response = $mk->post(Resources::MAILING_LISTS, null, $mailingListData);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint allows you to create a mailing list in your MailKitchen account.

HTTP Request

POST https://api.mailkitchen.com/v1/mailinglists

Query Parameters

Parameter Required Description
name true Name of the mailing list

Response

The response is formatted in JSON with the status of API's request. The mailing list will be add.

Field Description
id Mailing list's identifier in database
name Mailing list's name
creation_date Mailing list's record date
subscriber_count The number of subscribers in the mailing list

Update a mailing list

## API Endpoint
curl -X PUT https://api.mailkitchen.com/v1/mailinglists/<idMailingList>
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'
    -d '{ "name": "<nameMailingList>" }'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": {
        "id": 201,
        "name": "testdic3",
        "creation_date": "2019-10-24 19:21:09",
        "subscribers_count": 0
    }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>'; 
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$mailingListData = ['name' => '<nameMailingList>'];
$response = $mk->put(Resources::MAILING_LISTS, "<idMailingList>", $mailingListData);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint allows you to update a mailing list in your MailKitchen account.

HTTP Request

PUT https://api.mailkitchen.com/v1/mailinglists/<idMailingList>

Query Parameters

Parameter Required Description
name true Name of the mailing list

Response

The response is formatted in JSON with the status of API's request. The mailing list will be update.

Field Description
id Mailing list's identifier in database
name Mailing list's name
creation_date Mailing list's record date
subscriber_count The number of subscribers in the mailing list

Delete a mailing list

## API Endpoint
curl -X DELETE https://api.mailkitchen.com/v1/mailinglists/<idMailingList>
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": "The mailing list was deleted successfully!"
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>'; 
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->delete(Resources::MAILING_LISTS, "<idMailingList>");
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint allows you to delete a mailing list in your MailKitchen account.

HTTP Request

DELETE https://api.mailkitchen.com/v1/mailinglists/<idMailingList>

Response

The response is formatted in JSON with the status of API's request. The mailing list will be delete.

Get subscribers in mailing list

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/mailinglists/<idMailingList>/relationships/subscribers?limit=10&page=2
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": {
        "id": "39",
        "name": "test",
        "creation_date": "-0001-11-30 00:09:21",
        "subscriber_count_total": "33",
        "relationships": {
            "current_page": 2,
            "limit_per_page": 10,
            "count_per_page": 10,
            "total_count_page": 4,
            "subscribers": {
                "data": [
                    {
                        "id": "1412",
                        "email": "[email protected]",
                        "insertion_date": "2014-06-11 02:00:00",
                        "hard_bounce": null,
                        "soft_bounce": null,
                        "count_soft_bounce": "0"
                    },
                    ...
                    {
                        "id": "1422",
                        "email": "[email protected]",
                        "insertion_date": "2014-06-11 02:00:00",
                        "hard_bounce": null,
                        "soft_bounce": null,
                        "count_soft_bounce": "0"
                    }
                ]
            }
        }
    }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>'; 
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

// Default pagination
$response = $mk->get(Resources::MAILING_LISTS, "<idMailingList>", Resources::RELATIONSHIPS, Resources::SUBSCRIBERS);
print_r($response);

// Specific pagination
$paginationParams = [
    'limit' => "<limitNumber>",
    "page" => "<pageNumber>"
];
$response = $mk->get(Resources::MAILING_LISTS, "<idMailingList>", Resources::RELATIONSHIPS, Resources::SUBSCRIBERS, $paginationParams);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint retrieves subscribers in specific mailing list. In order to avoid an overload of the network because of too much data that endpoint returns, a pagination is useful. Without parameters set in the endpoint, the limit is 50,000 results by page. By the way, even if you set a parameter to increase the limit, it will be always 50,000.

HTTP Request

GET https://api.mailkitchen.com/v1/mailinglists/<idMailingList>/relationships/subscribers?<paginationQuery>

Query Parameters

Parameter Required Description
idMailingList true Mailing list's identifier in database
Query Parameters For Pagination
Parameter Required Description
limit false Define the number of results returned, by default is 50,000
page false Define which page is returned, by default is the first page

Response

The response is formatted in JSON with the status of API's request, you will get subscribers details in the mailing list.

Mailing list data
Field Description
id Mailing list's identifier in database
name Mailing list's email
creation_date Mailing list's record date
subscriber_count Subscribers number in the mailing list
current_page the page currently returned
limit_per_page the number of results returned by page
count_per_page the number of results returned by the current page
total_count_page the number of page which contains all results
Subscriber data
Field Description
id Subscriber's identifier in database
email Subscriber's email
insertion_date Subscriber's record date
hard_bounce A date when the subscriber's mailbox is definitively unreachable ('null' indicated the case).
soft_bounce A date when the subscriber's mailbox is temporarily unreachable ('null' indicated the case).
count_soft_bounce Number of attempt sent which the subscriber's mailbox is temporarily unreachable.

Clean hard bounce emails

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/mailinglists/<idMailingList>/tools/cleaning
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": "The mailing list was cleaned successfully. You have no more hard bounce emails!"
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>'; 
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->get(Resources::MAILING_LISTS, "<idMailingList>", Resources::TOOLS, Resources::CLEANING);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint allows you to clean hard bounce emails in specific mailing list.

HTTP Request

GET https://api.mailkitchen.com/v1/mailinglists/<idMailingList>/tools/cleaning

Query Parameters

Parameter Required Description
idMailingList true Mailing list's identifier in database

Response

The response is formatted in JSON with the status of API's request, the hard bounce emails will be remove from the mailing list.

Export data

## API Endpoint
curl -X POST https://api.mailkitchen.com/v1/mailinglists/<idMailingList>/tools/export
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'
    -d '{ "webhook": "<webhookUrl>" }'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": "Your request is being processed. Please wait a moment. Your webhook will receive the file."
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>'; 
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$exportData = [
    'webhook' => '<webhookUrl>'
];
$response = $mk->post(Resources::MAILING_LISTS, "<idMailingList>", $exportData, Resources::TOOLS, Resources::EXPORT);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint allows you to export data from specific mailing list. Like this endpoint may be return too much data, when you call it, please give us as parameter a webhook URL which receives the file exported we send us via POST method. Your webhook URL is verified before and if the response HTTP code is not '200', the export will not start.

HTTP Request

POST https://api.mailkitchen.com/v1/mailinglists/<idMailingList>/tools/export

Query Parameters

Parameter Required Description
webhook true An URL where the file will be upload on your server

Response

The response is formatted in JSON with the status of API's request, the export will contain data from the mailing list and when the export is done, your webhook will be call.

Import subscribers

## API Endpoint
curl -X POST https://api.mailkitchen.com/v1/mailinglists/<idMailingList>/relationships/subscribers
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'
    -d '{ "data": [{"email": "<youremail>", "custom_fields": {"<customFieldName>": "<customFieldValue>", ...}}, ...] }'

## JSON Response
{
  "api": {
    "version": "1.0",
    "http_status_code": 200,
    "http_message": "200 (OK)"
  },
  "data": {
    "message": "Your import will be proccessing. Your import has been added to the queue. We trigger your webhook url when import is ended.",
    "number_of_imports_pending": 0
  }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>'; 
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$importData = [
    'data' => [
        [
            'email'=> "<youremail>",
            'custom_fields' => [
                "<customFieldName>" => "<customFieldValue>",
                ...
            ]
        ],
        ...
    ]
];
$response = $mk->post(Resources::MAILING_LISTS, "<idMailingList>", $importData, Resources::RELATIONSHIPS, Resources::SUBSCRIBERS);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint allows you to import subscribers in a specific mailing list. Like this endpoint may be takes time if too much data when you call it, you need to have set an url of webhook to receive the notification when import has finished, and it ought to return a http code response "200" otherwise we can't import subscribers. Moreover, a limit of subscribers of 100 000 is set. So if you have more than the limit, please split them and make several calls.

HTTP Request

POST https://api.mailkitchen.com/v1/mailinglists/<idMailingList>/relationships/subscribers

Query Parameters

Parameter Required Description
data true the content of your emails in array
email true the email of the subscriber
custom_fields false if you need some details on subscribers, add custom fields (which is created before on your account)

Response

The response is formatted in JSON with the status of API's request, the import will contain data in the mailing list and when the import is done, your webhook will be call.

Unsubscribe Lists

An unsubscribe list allows you to define which contacts don't want to receive your emails. In this section, you can handle several unsubscribe lists and its contents.

Get all unsubscribe lists

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/unsubscribelists
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": [
        {
            "id": "2",
            "name": "List-Unsubscribe (default)",
            "subscriber_count": "9"
        },
        ...
        {
            "id": "455",
            "name": "testapi4",
            "subscriber_count": "0"
        }
    ]
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->get(Resources::UNSUBSCRIBE_LISTS);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint retrieves all unsubscribe lists in your MailKitchen account.

HTTP Request

GET https://api.mailkitchen.com/v1/unsubscribelists

Response

The response is formatted in JSON with the status of API's request, you will get all unsubscribe lists.

Field Description
id Unsubscribe list's identifier in database
name Unsubscribe list's name
subscriber_count The number of subscribers in the unsubscribe list

Get an unsubscribe list

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/unsubscribelists/<idUnsubscribeList>
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": {
        "id": "2",
        "name": "List-Unsubscribe (default)",
        "subscriber_count": "9"
    }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->get(Resources::UNSUBSCRIBE_LISTS, "<idUnsubscribeList>");
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint retrieves an unsubscribe list in your MailKitchen account.

HTTP Request

GET https://api.mailkitchen.com/v1/unsubscribelists/<idUnsubscribeList>

Response

The response is formatted in JSON with the status of API's request, you will get the unsubscribe list detail.

Field Description
id Unsubscribe list's identifier in database
name Unsubscribe list's name
subscriber_count The number of subscribers in the unsubscribe list

Get subscribers in unsubscribe list

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/unsubscribelists/<idUnsubscribeList>/relationships/subscribers?limit=5&page=2
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": {
        "id": "2",
        "name": "List-Unsubscribe (default)",
        "subscriber_count_total": "9",
        "relationships": {
            "current_page": 2,
            "limit_per_page": 5,
            "count_per_page": 4,
            "total_count_page": 2,
            "subscribers": {
                "data": [
                    {
                        "id": "6",
                        "email": "[email protected]",
                        "insertion_date": "2013-03-15 01:00:00",
                        "hard_bounce": null,
                        "soft_bounce": null,
                        "count_soft_bounce": "0"
                    },
                    ...
                    {
                        "id": "1378",
                        "email": "[email protected]",
                        "insertion_date": "2013-09-25 02:00:00",
                        "hard_bounce": null,
                        "soft_bounce": null,
                        "count_soft_bounce": "0"
                    }
                ]
            }
        }
    }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

// Default pagination
$response = $mk->get(Resources::UNSUBSCRIBE_LISTS, "<idUnsubscribeList>", Resources::RELATIONSHIPS, Resources::SUBSCRIBERS);
print_r($response);

// Specific pagination
$paginationParams = [
    'limit' => "<limitNumber>",
    "page" => "<pageNumber>"
];
$response = $mk->get(Resources::UNSUBSCRIBE_LISTS, "<idUnsubscribeList>", Resources::RELATIONSHIPS, Resources::SUBSCRIBERS, $paginationParams);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint retrieves subscribers in specific unsubscribe list. In order to avoid an overload of the network because of too much data that endpoint returns, a pagination is useful. Without parameters set in the endpoint, the limit is 50,000 results by page. By the way, even if you set a parameter to increase the limit, it will be always 50,000.

HTTP Request

GET https://api.mailkitchen.com/v1/unsubscribelists/<idUnsubscribeList>/relationships/subscribers?<paginationQuery>

Query Parameters

Parameter Required Description
idUnsubscribeList true Unsubscribe list's identifier in database
Query Parameters For Pagination
Parameter Required Description
limit false Define the number of results returned, by default is 50,000
page false Define which page is returned, by default is the first page

Response

The response is formatted in JSON with the status of API's request, you will get subscribers details in the unsubscribe list.

Unsubscribe list data
Field Description
id Unsubscribe list's identifier in database
name Unsubscribe list's email
subscriber_count Subscribers number in the unsubscribe list
current_page the page currently returned
limit_per_page the number of results returned by page
count_per_page the number of results returned by the current page
total_count_page the number of page which contains all results
Subscriber data
Field Description
id Subscriber's identifier in database
email Subscriber's email
insertion_date Subscriber's record date
hard_bounce A date when the subscriber's mailbox is definitively unreachable ('null' indicated the case).
soft_bounce A date when the subscriber's mailbox is temporarily unreachable ('null' indicated the case).
count_soft_bounce Number of attempt sent which the subscriber's mailbox is temporarily unreachable.

Export data

## API Endpoint
curl -X POST https://api.mailkitchen.com/v1/unsubscribelists/<idUnsubscribeList>/tools/export
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'
    -d '{ "webhook": "<webhookUrl>" }'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": "Your request is being processed. Please wait a moment. Your webhook will receive the file."
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$exportData = [
    'webhook' => "<webhookUrl>"
];
$response = $mk->post(Resources::UNSUBSCRIBE_LISTS, "<idUnsubscribeList>", $exportData, Resources::TOOLS, Resources::EXPORT);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint allows you to export data from specific unsubscribe list. Like this endpoint may be return too much data, when you call it, please give us as parameter a webhook URL which receives the file exported we send us via POST method. Your webhook URL is verified before and if the response HTTP code is not '200', the export will not start.

HTTP Request

POST https://api.mailkitchen.com/v1/unsubscribelists/<idUnsubscribeList>/tools/export

Query Parameters

Parameter Required Description
webhook false An URL where the file will be upload on your server

Response

The response is formatted in JSON with the status of API's request, the export will contain data from the unsubscribe list and when the export is done, your webhook will be call.

Segments

A segment allows you to define which contacts you want send an email with conditions. In this section, you can retrieve several segments.

Get all segments

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/segments
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": [
        {
            "id": "71",
            "name": "segment_test_2",
            "subscriber_count": "52",
            "modification_date": "2014-06-16 11:49:03"
        },
        ...
        {
            "id": "559",
            "name": "[MK] ouvreur_l98",
            "subscriber_count": "0",
            "modification_date": "2019-11-13 17:27:22"
        }
    ]
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->get(Resources::SEGMENTS);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint retrieves all segments in your MailKitchen account.

HTTP Request

GET https://api.mailkitchen.com/v1/segments

Response

The response is formatted in JSON with the status of API's request, you will get all segments.

Field Description
id Segment's identifier in database
name Segment's name
subscriber_count The number of subscribers in the segment
modification_date The last update date of the number of subscribers

Get a segment

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/segments/<segmentId>
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": {
        "id": "71",
        "name": "segment_test_2",
        "subscriber_count": "52",
        "modification_date": "2014-06-16 11:49:03"
    }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->get(Resources::SEGMENTS, "<segmentId>");
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint retrieves a segment in your MailKitchen account.

HTTP Request

GET https://api.mailkitchen.com/v1/segments/<segmentId>

Response

The response is formatted in JSON with the status of API's request, you will get a segment.

Field Description
id Segment's identifier in database
name Segment's name
subscriber_count The number of subscribers in the segment
modification_date The last update date of the number of subscribers

Refresh a segment

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/segments/<segmentId>/tools/refresh
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": "Your segment has been updated."
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->get(Resources::SEGMENTS, "<segmentId>", Resources::TOOLS, Resources::REFRESH);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint refresh the count of subscribers un a segment in your MailKitchen account.

HTTP Request

GET https://api.mailkitchen.com/v1/segments/<segmentId>/tools/refresh

Response

The response is formatted in JSON with the status of API's request, you will refresh the count of subscribers in a segment.

Field Description
id Segment's identifier in database
name Segment's name
subscriber_count The number of subscribers in the segment
modification_date The last update date of the number of subscribers

Campaigns

MailKitchen API allows you to handle your campaigns. You will be able to program campaigns, test and send them. You will get statistics of your campaigns and follow them.

Get all campaigns

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/campaigns
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": [
        {
            "id": "4",
            "name": "newsdetest",
            "creation_date": "2013-03-15 12:17:42",
            "modification_date": "2013-04-02 16:29:08",
            "status": "en attente de ciblage"
        },
        ...
        {
            "id": "1212",
            "name": "tgok42rteg",
            "creation_date": "2019-12-03 17:07:00",
            "modification_date": "2019-12-04 11:45:07",
            "status": "en creation"
        }
    ]
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->get(Resources::CAMPAIGNS);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

Get all campaigns of your account and retrieve some details about them.

HTTP Request

GET https://api.mailkitchen.com/v1/campaigns

Response

The response is formatted in JSON with the status of API's request, you will get all campaigns details.

Field Description
id Campaign's identifier in database
name Campaign's name
creation_date Campaign's record date
modification_date Campaign's update date
status Campaign's status

Get a specific campaign

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/campaigns/<campaignId>
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": {
        "id": "1008",
        "name": "news31/12/15 10:36",
        "creation_date": "2015-12-31 11:32:43",
        "modification_date": "2015-12-31 11:34:02",
        "status": "en creation"
    }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->get(Resources::CAMPAIGNS, "<campaignId>");
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint retrieves a specific campaign with some details.

HTTP Request

GET https://api.mailkitchen.com/v1/campaigns/<campaignId>

Query Parameters

Parameter Required Description
campaignId true Campaign's identifier in database

Response

The response is formatted in JSON with the status of API's request, you will get a campaign details.

Field Description
id Campaign's identifier in database
name Campaign's name
creation_date Campaign's record date
modification_date Campaign's update date
status Campaign's status

Create a campaign

## API Endpoint
curl -X POST https://api.mailkitchen.com/v1/campaigns
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'
    -d '{
        "name": <campaignName>,
        "alias": [<aliasName1>, <aliasName2>, ...],
        "objet": [<object1>, <object2>, ...],
        "corps": [<body1>, <body2>, ...],
        "type": <campaignType>,
        "id_liste_desinscription": [<unsubscribeList1>, <unsubscribeList2>, ...],
        "id_expediteur": <senderId>,
        "add_segment": [<segmentId1>, <segmentId2>, ...],
        "sup_segment": [<segmentId1>, <segmentId2>, ...],
        "add_liste_diffusion": [<mailingList1>, <mailingList2>, ...],
        "sup_liste_diffusion": [<mailingList1>, <mailingList2>, ...],
    }'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 201,
        "http_message": "201 (Created)"
    },
    "data": {
        "id": "1239",
        "name": "testonslapi25",
        "creation_date": "2020-01-02 17:11:34"
    }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$campaignData = [
        "name" => "<campaignName>",
        "alias" => ["<aliasName1>", "<aliasName2>", ...],
        "objet" => ["<object1>", "<object2>", ...],
        "corps" => ["<body1>", "<body2>", ...],
        "type" => "<campaignType>",
        "id_liste_desinscription" => ["<unsubscribeList1>", "<unsubscribeList2>", ...],
        "id_expediteur" => "<senderId>",
        "add_segment" => ["<segmentId1>", "<segmentId2>", ...],
        "sup_segment" => ["<segmentId1>", "<segmentId2>", ...],
        "add_liste_diffusion" => ["<mailingList1>", "<mailingList2>", ...],
        "sup_liste_diffusion" => ["<mailingList1>", "<mailingList2>", ...]
];
$response = $mk->post(Resources::CAMPAIGNS, null, $campaignData);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint allows you to create a campaign in your MailKitchen account.

HTTP Request

POST https://api.mailkitchen.com/v1/campaigns

Query Parameters

Parameter Required Description
name true Campaign's name
alias true Campaign's alias, an array with some aliases
objet true Campaign's objects, an array with some objects
corps true Campaign's bodies, an array with some bodies
type true Campaign's programmation, "unique" or "planifie"
id_liste_desinscription true Unsubscribe lists to associate with the campaign, an array with identifiers of unsubscribe lists
id_expediteur true Sender to associate with the campaign, an array with identifiers of senders
add_segment true Segment to include in the campaign, an array with identifiers of segments
sup_segment true Segment to exclude from the campaign, an array with identifiers of segments
add_liste_diffusion true Mailing list to include in the campaign, an array with identifiers of mailing lists
sup_liste_diffusion true Mailing list to exclude from the campaign, an array with identifiers of mailing lists
debut false If campaign is scheduled, this field allows you to define when the campaign starts
fin false If campaign is scheduled, this field allows you to define when the campaign end
jour false If campaign is scheduled, this field allows you to define the day when the campaign send
heure false If campaign is scheduled, this field allows you to define the hour when the campaign send
minute false If campaign is scheduled, this field allows you to define the minutes when the campaign send

Response

The response is formatted in JSON with the status of API's request, your campaign is created.

Field Description
id Campaign's identifier in database
name Campaign's name
creation_date Campaign's record date

Update a campaign

## API Endpoint
curl -X PUT https://api.mailkitchen.com/v1/campaings/<campaignId>
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'
    -d '{"<someDataToUpdate>": "<someValueOfDataToUpdate>"}'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": {
        "id": 1239,
        "name": "testapiupdate3",
        "modification_date": "2020-01-15 11:18:28"
    }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$campaignData = [
        "name" => "<campaignName>",
        "alias" => ["<aliasName1>", "<aliasName2>", ...],
        "objet" => ["<object1>", "<object2>", ...],
        "corps" => ["<body1>", "<body2>", ...],
        "type" => "<campaignType>",
        "id_liste_desinscription" => ["<unsubscribeList1>", "<unsubscribeList2>", ...],
        "id_expediteur" => "<senderId>",
        "add_segment" => ["<segmentId1>", "<segmentId2>", ...],
        "sup_segment" => ["<segmentId1>", "<segmentId2>", ...],
        "add_liste_diffusion" => ["<mailingList1>", "<mailingList2>", ...],
        "sup_liste_diffusion" => ["<mailingList1>", "<mailingList2>", ...]
];
$response = $mk->put(Resources::CAMPAIGNS, "<campaignId>", $campaignData);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint allows you to update a campaign in your MailKitchen account.

HTTP Request

PUT https://api.mailkitchen.com/v1/campaings/<campaignId>

Response

The response is formatted in JSON with the status of API's request, the campaign will be updated.

Field Description
id Campaign's identifier in database
name Campaign's name
modification_date Campaign's update date

Delete a campaign

## API Endpoint
curl -X DELETE https://api.mailkitchen.com/v1/campaigns/<campaignId>
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": "The campaign was deleted successfully!"
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->delete(Resources::CAMPAIGNS, "<campaignId>");
print_r($response);
?>

This endpoint allows you to delete a campaign in your MailKitchen account.

HTTP Request

DELETE https://api.mailkitchen.com/v1/campaigns/<campaignId>

Query Parameters

Parameter Required Description
campaignId true Campaign's identifier in the database

Response

The response is formatted in JSON with the status of API's request. The custom field will be delete.

Campaign validation

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/campaigns/<campaignId>/tools/validate
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": {
        "message": "Your campaign has been validated successfully !",
        "spamScore": {
            "success": 1,
            "header": {
                "1": "0.0 FROM_LOCAL_DIGITS      From: localpart has long digit sequence\n 0.0 FROM_LOCAL_HEX         From: localpart has long hexadecimal sequence\n 0.1 TRACKER_ID             BODY: Incorporates a tracking ID number\n 0.0 HTML_MESSAGE           BODY: HTML included in message\n 0.0 TVD_SPACE_RATIO        No description available.\n 2.5 TVD_SPACE_RATIO_MINFP  Space ratio\n\npossible-languages     ="
            },
            "retour": {
                "1": {
                    "score": 2.6
                }
            },
            "report": {
                "1": [
                    "FROM_LOCAL_DIGITS",
                    "FROM_LOCAL_HEX",
                    "HTML_MESSAGE",
                    "TRACKER_ID",
                    "TVD_SPACE_RATIO",
                    "TVD_SPACE_RATIO_MINFP"
                ]
            },
            "activation": true,
            "translation": {
                "1": [
                    {
                        "trad": "",
                        "note": "0.1",
                        "text": "BODY: Incorporates a tracking ID number",
                        "code": "TRACKER_ID"
                    },
                    {
                        "trad": "",
                        "note": "2.5",
                        "text": "Space ratio",
                        "code": "TVD_SPACE_RATIO_MINFP"
                    }
                ]
            }
        }
    }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->get(Resources::CAMPAIGNS, "<campaignId>", Resources::TOOLS, Resources::VALIDATE);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint allows you to validate your campaign. You need to validate the campaign before to send it.

HTTP Request

GET https://api.mailkitchen.com/v1/campaigns/<campaignId>/tools/validate

Query Parameters

Parameter Required Description
campaignId true Campaign's identifier in the database

Response

The response is formatted in JSON with the status of API's request, you know if your campaign is good to send it or not.

Response Spam Assassin OK
Field Description
spamScore The result of test by SpamAssassin tool, You will find some information which help you to increase the reliability of your campaign and avoid spam result.
Response Spam Assassin KO
Field Description
spamScore The result of test by SpamAssassin tool, You will find some information which help you to modify the reliability of your campaign and avoid spam result.
Response KO
Field Description
errors Message of error which tell you what is bad.

Campaign sending test (BAT)

## API Endpoint
curl -X POST https://api.mailkitchen.com/v1/campaigns/<campaignId>/tools/bat
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'
    -d '{"email": "<recipientEmail>"}'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": "Your test email has been successfully sent"
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$batData = [
    'email' => "<recipientEmail>"
];
$response = $mk->post(Resources::CAMPAIGNS, "<campaignId>", $batData, Resources::TOOLS, Resources::BAT);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint allow you to test your campaign by sending an email test (BAT).

HTTP Request

POST https://api.mailkitchen.com/v1/campaigns/<campaignId>/tools/bat

Response

The response is formatted in JSON with the status of API's request, you will send an email test of your campaign.

Get all senders

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/senders
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": [
        {
            "id": "35",
            "name": "adresse perso",
            "from": "[email protected]",
            "reply": null,
            "domain": null
        },
        {
            "id": "41",
            "name": "mon expe de test",
            "from": "[email protected]",
            "reply": "[email protected]",
            "domain": null
        }
    ]
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->get(Resources::SENDERS);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint allows you to get all senders in your MailKitchen account.

HTTP Request

GET https://api.mailkitchen.com/v1/senders

Response

The response is formatted in JSON with the status of API's request. You will get all senders associated in your MailKitchen account.

Field Description
id Sender's identifier in database
name Sender's name
from Sender's email address
reply Email address of reply for sender's email address

Get a sender

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/senders/<idSender>
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
    "api": {
        "version": "1.0",
        "http_status_code": 200,
        "http_message": "200 (OK)"
    },
    "data": {
        "id": "35",
        "name": "adresse perso",
        "from": "[email protected]",
        "reply": null
    }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->get(Resources::SENDERS, "<idSender>");
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint allows you to get a specific sender in your MailKitchen account.

HTTP Request

GET https://api.mailkitchen.com/v1/senders/<idSender>

Query Parameters

Parameter Required Description
idSender true Sender's identifier in database

Response

The response is formatted in JSON with the status of API's request. You will get information about a specific sender.

Field Description
id Sender's identifier in database
name Sender's name
from Sender's email address

Statistics

MailKitchen API allows you to get statistics about your account, statistics of your campaigns and follow them. Moreover, specific statistics are available to let you refine yours campaigns.

Account stats

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/statistics
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
  "api": {
    "version": "1.0",
    "http_status_code": 200,
    "http_message": "200 (OK)"
  },
  "data": {
    "NbEnvoi": "4,508,748",
    "NbOuverture": "383,013",
    "NbDestinataire": "4,511,404",
    "NbClic": "30,670",
    "NbOuvertureUnique": "204,025",
    "NbClicUnique": "13,074",
    "NbDesinscription": "12,168",
    "NbTransformation": "8",
    "NbSoftBounce": "13,874",
    "NbHardBounce": "37,850",
    "NbFailure": "192,000",
    "NbPlainte": "721",
    "NbAbuse": "182",
    "NbBounceIndetermine": "37,279",
    "NbEnAttente": "2,656",
    "NbBounce": "89,003",
    "NbNonAbouti": 281542,
    "NbReussiBrut": 4227745,
    "NbReussi": "4,227,745",
    "NbNonReactif": "4,023,720",
    "NbCibleBrut": "4511404",
    "NbEnvoiBrut": "4508748",
    "NbOuvertureBrut": "383013",
    "NbClicBrut": "30670",
    "NbTransformationBrut": "8",
    "TxEnAttente": "0.06%",
    "TxReussiBrut": 0.94,
    "TxOuvertureBrut": 0.09,
    "TxOuverture": "9%",
    "TxOuvertureUnique": "53%",
    "TxClic": "8%",
    "TxClicBrut": 0.08,
    "TxClicUnique": "43%",
    "TxDesinscriptionBrut": 0.0027,
    "TxEnvoie": "100%",
    "TxTransformationBrut": 0.0003,
    "TxClic_Ouv": "8.01%",
    "TxClicUnique_Ouv": "6.41%",
    "TxBounceBrut": 0.0197,
    "TxHardBounce": "0.84%",
    "TxSoftBounce": "0.31%",
    "TxFailureBrut": 0.0426,
    "TxPlainteBrut": 0.0002,
    "TxBounceIndetermine": "0.83%",
    "TxOuvertureUnique_Dest": "4.52%",
    "TxClicUnique_Dest": "0.29%",
    "TxDesinscription_Dest": "0.27%",
    "TxBounce_Dest": "1.97%",
    "TxEnAttente_Dest": "0.06%",
    "TxNonReactif_Dest": "89.19%",
    "NbCible": "4,511,404",
    "TxReussi": "94%",
    "TxTransformation": "0.03%",
    "TxBounce": "1.97%",
    "TxFailure": "4.26%",
    "TxPlainte": "0.02%",
    "TxDesinscription": "0.27%"
  }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$response = $mk->get(Resources::STATISTICS);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

Get all statistics about your account from the start of it.

HTTP Request

GET https://api.mailkitchen.com/v1/statistics

Response

The response is formatted in JSON with the status of API's request, you will get all statistics details.

Field Description
NbEnvoi Number formatted of emails sent
NbOuverture Number formatted of emails opened
NbDestinataire Number of subscribers to whom emails have been sent
NbClic Number formatted of emails which recorded a click
NbOuvertureUnique Number of unique open emails
NbClicUnique Number of unique click emails
NbDesinscription Number of unsubscribe demand recorded
NbTransformation Number formatted of emails whom subscribers transformed with a tag included in emails
NbSoftBounce Number of emails which has temporarily refused
NbHardBounce Number of emails which has definitively refused
NbFailure Number of emails which has not sent
NbPlainte Number of emails which has received complaints
NbAbuse Number of emails which has been declared as spam by subscribers
NbBounceIndetermine Number of emails which has refused but we don't know the reason
NbEnAttente Number of emails are pending to send
NbBounce Number of total emails which has been refused
NbNonAbouti Number of emails not received by subscribers
NbReussiBrut Number of emails which has been received by subscribers
NbReussi Number formatted of emails which has been received by subscribers
NbNonReactif Number of emails which has been received but no activity from subscribers
NbCibleBrut Number of subscribers to whom emails have been sent
NbEnvoiBrut Number of emails sent
NbOuvertureBrut Number of emails opened
NbClicBrut Number of emails which recorded a click
NbTransformationBrut Number of emails whom subscribers transformed with a tag included in emails
TxEnAttente The rate of emails which are pending to send
TxReussiBrut The rate of emails which has been received
TxOuvertureBrut The rate of emails opened
TxOuverture The rate formatted of emails opened
TxOuvertureUnique The rate of emails opened
TxClic The rate formatted of emails which has recorded a click
TxClicBrut The rate of emails which has recorded a click
TxClicUnique The rate of emails which has recorded a single click
TxDesinscriptionBrut The rate of emails which has recorded an unsubscribe demand
TxEnvoie The rate of emails sent
TxTransformationBrut The rate of emails whom subscribers transformed with a tag included in emails
TxClic_Ouv The rate of clicks on opened emails
TxClicUnique_Ouv The rate of single click on opened emails
TxBounceBrut The rate of emails which has been refused
TxHardBounce The rate of emails which has been definitively refused
TxSoftBounce The rate of emails which has been temporarily refused
TxFailureBrut The rate of emails which has not been sent
TxPlainteBrut The rate of emails which has recorded complaints
TxBounceIndetermine The rate of emails which has refused but we don't know the reason
TxOuvertureUnique_Dest The rate of single open emails on subscribers
TxClicUnique_Dest The rate of single click on subscribers
TxDesinscription_Dest The rate of unsubscribe demand on subscribers
TxBounce_Dest The rate of emails which has not been received on subscribers
TxEnAttente_Dest The rate of emails which are pending on subscribers
TxNonReactif_Dest The rate of emails which has been received but no activity from subscribers on subscribers
NbCible Number formatted of subscribers to whom emails have been sent
TxReussi The rate formatted of emails which has been received
TxTransformation The rate formatted of emails whom subscribers transformed with a tag included in emails
TxBounce The rate formatted of emails which has been refused
TxFailure The rate formatted of emails which has not been sent
TxPlainte The rate formatted of emails which has recorded complaints
TxDesinscription The rate formatted of emails which has recorded an unsubscribe demand stats

Campaigns stats

In this section, you will get statistics of your campaigns and moreover have details about some criteria. You will be able to fit your research using query parameters. Indeed, you will be able to filter by campaign's identifier and by timeline with a start and an end date.

General

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/statistics/campaigns
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
  "api": {
    "version": "1.0",
    "http_status_code": 200,
    "http_message": "200 (OK)"
  },
  "data": [
    {
      "Id": 40030,
      "Nom": "News: Module des templates (août 2013)",
      "DateEnvoi": "2013-08-28 09:10:00",
      "NbDestinataire": "478",
      "NbEnvoi": "478",
      "NbOuverture": "297",
      "NbClic": "44",
      "NbOuvertureUnique": "100",
      "NbClicUnique": "25",
      "NbDesinscription": "5",
      "NbTransformation": "0",
      "NbSoftBounce": "0",
      "NbHardBounce": "0",
      "NbFailure": "0",
      "NbPlainte": "0",
      "NbAbuse": "0",
      "NbBounceIndetermine": "0",
      "NbEnAttente": "0",
      "NbBounce": "0",
      "NbNonAbouti": 0,
      "NbReussiBrut": 478,
      "NbReussi": "478",
      "NbNonReactif": "378",
      "NbCibleBrut": "478",
      "NbEnvoiBrut": "478",
      "NbOuvertureBrut": "297",
      "NbClicBrut": "44",
      "NbTransformationBrut": "0",
      "TxEnAttente": "0%",
      "TxReussiBrut": 1,
      "TxOuvertureBrut": 0.62,
      "TxOuverture": "62%",
      "TxOuvertureUnique": "34%",
      "TxClic": "15%",
      "TxClicBrut": 0.15,
      "TxClicUnique": "57%",
      "TxDesinscriptionBrut": 0.0105,
      "TxEnvoie": "100%",
      "TxTransformationBrut": 0,
      "TxClic_Ouv": "14.81%",
      "TxClicUnique_Ouv": "25%",
      "TxBounceBrut": 0,
      "TxHardBounce": "0%",
      "TxSoftBounce": "0%",
      "TxFailureBrut": 0,
      "TxPlainteBrut": 0,
      "TxBounceIndetermine": "0%",
      "TxOuvertureUnique_Dest": "20.92%",
      "TxClicUnique_Dest": "5.23%",
      "TxDesinscription_Dest": "1.05%",
      "TxBounce_Dest": "0%",
      "TxEnAttente_Dest": "0%",
      "TxNonReactif_Dest": "79.08%",
      "NbCible": "478",
      "TxReussi": "100%",
      "TxTransformation": "0%",
      "TxBounce": "0%",
      "TxFailure": "0%",
      "TxPlainte": "0%",
      "TxDesinscription": "1.05%"
    },
    ...
  ]
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

// With filter parameters
$query = [
    'id_mail' => "<id_mail>",
    'startStat' => '<startStat>',
    'endStat' => '<endStat>'
];
$response = $mk->get(Resources::STATISTICS, null, Resources::CAMPAIGNS, null, $query);
print_r($response);

// Without filter parameters
$response = $mk->get(Resources::STATISTICS, null, Resources::CAMPAIGNS);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint retrieves statistics of campaigns.

HTTP Request

GET https://api.mailkitchen.com/v1/statistics/campaigns

Query Parameters

Parameter Required Description
id_mail false Campaign's identifier in database
startStat false The start date whom you want to get statistics
endStat false The end date whom you want to get statistics

Response

The response is formatted in JSON with the status of API's request, you will get campaigns statistics.

Field Description
Id Campaign's identifier in the database
Nom Campaign's name
DateEnvoi The sent date of the campaign
NbDestinataire Number of subscribers to whom emails have been sent
NbEnvoi Number formatted of emails sent
NbOuverture Number formatted of emails opened
NbDestinataire Number of subscribers to whom emails have been sent
NbClic Number formatted of emails which recorded a click
NbOuvertureUnique Number of unique open emails
NbClicUnique Number of unique click emails
NbDesinscription Number of unsubscribe demand recorded
NbTransformation Number formatted of emails whom subscribers transformed with a tag included in emails
NbSoftBounce Number of emails which has temporarily refused
NbHardBounce Number of emails which has definitively refused
NbFailure Number of emails which has not sent
NbPlainte Number of emails which has received complaints
NbAbuse Number of emails which has been declared as spam by subscribers
NbBounceIndetermine Number of emails which has refused but we don't know the reason
NbEnAttente Number of emails are pending to send
NbBounce Number of total emails which has been refused
NbNonAbouti Number of emails not received by subscribers
NbReussiBrut Number of emails which has been received by subscribers
NbReussi Number formatted of emails which has been received by subscribers
NbNonReactif Number of emails which has been received but no activity from subscribers
NbCibleBrut Number of subscribers to whom emails have been sent
NbEnvoiBrut Number of emails sent
NbOuvertureBrut Number of emails opened
NbClicBrut Number of emails which recorded a click
NbTransformationBrut Number of emails whom subscribers transformed with a tag included in emails
TxEnAttente The rate of emails which are pending to send
TxReussiBrut The rate of emails which has been received
TxOuvertureBrut The rate of emails opened
TxOuverture The rate formatted of emails opened
TxOuvertureUnique The rate of emails opened
TxClic The rate formatted of emails which has recorded a click
TxClicBrut The rate of emails which has recorded a click
TxClicUnique The rate of emails which has recorded a single click
TxDesinscriptionBrut The rate of emails which has recorded an unsubscribe demand
TxEnvoie The rate of emails sent
TxTransformationBrut The rate of emails whom subscribers transformed with a tag included in emails
TxClic_Ouv The rate of clicks on opened emails
TxClicUnique_Ouv The rate of single click on opened emails
TxBounceBrut The rate of emails which has been refused
TxHardBounce The rate of emails which has been definitively refused
TxSoftBounce The rate of emails which has been temporarily refused
TxFailureBrut The rate of emails which has not been sent
TxPlainteBrut The rate of emails which has recorded complaints
TxBounceIndetermine The rate of emails which has refused but we don't know the reason
TxOuvertureUnique_Dest The rate of single open emails on subscribers
TxClicUnique_Dest The rate of single click on subscribers
TxDesinscription_Dest The rate of unsubscribe demand on subscribers
TxBounce_Dest The rate of emails which has not been received on subscribers
TxEnAttente_Dest The rate of emails which are pending on subscribers
TxNonReactif_Dest The rate of emails which has been received but no activity from subscribers on subscribers
NbCible Number formatted of subscribers to whom emails have been sent
TxReussi The rate formatted of emails which has been received
TxTransformation The rate formatted of emails whom subscribers transformed with a tag included in emails
TxBounce The rate formatted of emails which has been refused
TxFailure The rate formatted of emails which has not been sent
TxPlainte The rate formatted of emails which has recorded complaints
TxDesinscription The rate formatted of emails which has recorded an unsubscribe demand

Global

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/statistics/campaigns/global
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
  "api": {
    "version": "1.0",
    "http_status_code": 200,
    "http_message": "200 (OK)"
  },
  "data": {
    "NbDestinataire": "4,511,404",
    "NbEnvoi": "4,508,748",
    "NbOuverture": "383,138",
    "NbClic": "30,674",
    "NbOuvertureUnique": "204,090",
    "NbClicUnique": "13,078",
    "NbDesinscription": "12,170",
    "NbTransformation": "8",
    "NbSoftBounce": "13,878",
    "NbHardBounce": "37,850",
    "NbFailure": "192,000",
    "NbPlainte": "721",
    "NbAbuse": "182",
    "NbBounceIndetermine": "37,279",
    "NbEnAttente": "2,656",
    "NbBounce": "89,007",
    "NbNonAbouti": 281546,
    "NbReussiBrut": 4227741,
    "NbReussi": "4,227,741",
    "NbNonReactif": "4,023,651",
    "NbCibleBrut": "4511404",
    "NbEnvoiBrut": "4508748",
    "NbOuvertureBrut": "383138",
    "NbClicBrut": "30674",
    "NbTransformationBrut": "8",
    "TxEnAttente": "0.06%",
    "TxReussiBrut": 0.94,
    "TxOuvertureBrut": 0.09,
    "TxOuverture": "9%",
    "TxOuvertureUnique": "53%",
    "TxClic": "8%",
    "TxClicBrut": 0.08,
    "TxClicUnique": "43%",
    "TxDesinscriptionBrut": 0.0027,
    "TxEnvoie": "100%",
    "TxTransformationBrut": 0.0003,
    "TxClic_Ouv": "8.01%",
    "TxClicUnique_Ouv": "6.41%",
    "TxBounceBrut": 0.0197,
    "TxHardBounce": "0.84%",
    "TxSoftBounce": "0.31%",
    "TxFailureBrut": 0.0426,
    "TxPlainteBrut": 0.0002,
    "TxBounceIndetermine": "0.83%",
    "TxOuvertureUnique_Dest": "4.52%",
    "TxClicUnique_Dest": "0.29%",
    "TxDesinscription_Dest": "0.27%",
    "TxBounce_Dest": "1.97%",
    "TxEnAttente_Dest": "0.06%",
    "TxNonReactif_Dest": "89.19%",
    "NbCible": "4,511,404",
    "TxReussi": "94%",
    "TxTransformation": "0.03%",
    "TxBounce": "1.97%",
    "TxFailure": "4.26%",
    "TxPlainte": "0.02%",
    "TxDesinscription": "0.27%"
  }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

// With filter parameters
$query = [
    'id_mail' => "<id_mail>",
    'startStat' => '<startStat>',
    'endStat' => '<endStat>'
];
$response = $mk->get(Resources::STATISTICS, null, Resources::CAMPAIGNS, Resources::GLOBALS, $query);
print_r($response);

// Without filter parameters
$response = $mk->get(Resources::STATISTICS, null, Resources::CAMPAIGNS, Resources::GLOBALS);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint retrieves global statistics about campaigns in your account.

HTTP Request

GET https://api.mailkitchen.com/v1/statistics/campaigns/global

Query Parameters

Parameter Required Description
id_mail false Campaign's identifier in database
startStat false The start date whom you want to get statistics
endStat false The end date whom you want to get statistics

Response

The response is formatted in JSON with the status of API's request, you will get campaign statistics.

Field Description
NbDestinataire Number of subscribers to whom emails have been sent
NbEnvoi Number formatted of emails sent
NbOuverture Number formatted of emails opened
NbClic Number formatted of emails which recorded a click
NbOuvertureUnique Number of unique open emails
NbClicUnique Number of unique click emails
NbDesinscription Number of unsubscribe demand recorded
NbTransformation Number formatted of emails whom subscribers transformed with a tag included in emails
NbSoftBounce Number of emails which has temporarily refused
NbHardBounce Number of emails which has definitively refused
NbFailure Number of emails which has not sent
NbPlainte Number of emails which has received complaints
NbAbuse Number of emails which has been declared as spam by subscribers
NbBounceIndetermine Number of emails which has refused but we don't know the reason
NbEnAttente Number of emails are pending to send
NbBounce Number of total emails which has been refused
NbNonAbouti Number of emails not received by subscribers
NbReussiBrut Number of emails which has been received by subscribers
NbReussi Number formatted of emails which has been received by subscribers
NbNonReactif Number of emails which has been received but no activity from subscribers
NbCibleBrut Number of subscribers to whom emails have been sent
NbEnvoiBrut Number of emails sent
NbOuvertureBrut Number of emails opened
NbClicBrut Number of emails which recorded a click
NbTransformationBrut Number of emails whom subscribers transformed with a tag included in emails
TxEnAttente The rate of emails which are pending to send
TxReussiBrut The rate of emails which has been received
TxOuvertureBrut The rate of emails opened
TxOuverture The rate formatted of emails opened
TxOuvertureUnique The rate of emails opened
TxClic The rate formatted of emails which has recorded a click
TxClicBrut The rate of emails which has recorded a click
TxClicUnique The rate of emails which has recorded a single click
TxDesinscriptionBrut The rate of emails which has recorded an unsubscribe demand
TxEnvoie The rate of emails sent
TxTransformationBrut The rate of emails whom subscribers transformed with a tag included in emails
TxClic_Ouv The rate of clicks on opened emails
TxClicUnique_Ouv The rate of single click on opened emails
TxBounceBrut The rate of emails which has been refused
TxHardBounce The rate of emails which has been definitively refused
TxSoftBounce The rate of emails which has been temporarily refused
TxFailureBrut The rate of emails which has not been sent
TxPlainteBrut The rate of emails which has recorded complaints
TxBounceIndetermine The rate of emails which has refused but we don't know the reason
TxOuvertureUnique_Dest The rate of single open emails on subscribers
TxClicUnique_Dest The rate of single click on subscribers
TxDesinscription_Dest The rate of unsubscribe demand on subscribers
TxBounce_Dest The rate of emails which has not been received on subscribers
TxEnAttente_Dest The rate of emails which are pending on subscribers
TxNonReactif_Dest The rate of emails which has been received but no activity from subscribers on subscribers
NbCible Number formatted of subscribers to whom emails have been sent
TxReussi The rate formatted of emails which has been received
TxTransformation The rate formatted of emails whom subscribers transformed with a tag included in emails
TxBounce The rate formatted of emails which has been refused
TxFailure The rate formatted of emails which has not been sent
TxPlainte The rate formatted of emails which has recorded complaints
TxDesinscription The rate formatted of emails which has recorded an unsubscribe demand

Provider

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/statistics/campaigns/provider
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
  "api": {
    "version": "1.0",
    "http_status_code": 200,
    "http_message": "200 (OK)"
  },
  "data": {
    "AOL": {
      "NbDestinataire": "15,015",
      "NbEnvoi": "15,006",
      "NbOuverture": "720",
      "NbClic": "59",
      "NbOuvertureUnique": "459",
      "NbClicUnique": "47",
      "NbDesinscription": "25",
      "NbTransformation": "0",
      "NbSoftBounce": "0",
      "NbHardBounce": "188",
      "NbFailure": "6,265",
      "NbPlainte": "15",
      "NbAbuse": "2",
      "NbBounceIndetermine": "2,279",
      "provider": "AOL",
      "NbEnAttente": "9",
      "NbBounce": "2,467",
      "NbNonAbouti": 8745,
      "NbReussiBrut": 6274,
      "NbReussi": "6,274",
      "NbNonReactif": "5,815",
      "NbCibleBrut": "15015",
      "NbEnvoiBrut": "15006",
      "NbOuvertureBrut": "720",
      "NbClicBrut": "59",
      "NbTransformationBrut": "0",
      "TxEnAttente": "0.06%",
      "TxReussiBrut": 0.42,
      "TxOuvertureBrut": 0.11,
      "TxOuverture": "11%",
      "TxOuvertureUnique": "64%",
      "TxClic": "8%",
      "TxClicBrut": 0.08,
      "TxClicUnique": "80%",
      "TxDesinscriptionBrut": 0.0017,
      "TxEnvoie": "100%",
      "TxTransformationBrut": 0,
      "TxClic_Ouv": "8.19%",
      "TxClicUnique_Ouv": "10.24%",
      "TxBounceBrut": 0.1644,
      "TxHardBounce": "1.25%",
      "TxSoftBounce": "0%",
      "TxFailureBrut": 0.4175,
      "TxPlainteBrut": 0.001,
      "TxBounceIndetermine": "15.19%",
      "TxOuvertureUnique_Dest": "3.06%",
      "TxClicUnique_Dest": "0.31%",
      "TxDesinscription_Dest": "0.17%",
      "TxBounce_Dest": "16.43%",
      "TxEnAttente_Dest": "0.06%",
      "TxNonReactif_Dest": "38.73%",
      "NbCible": "15,015",
      "TxReussi": "42%",
      "TxTransformation": "0%",
      "TxBounce": "16.44%",
      "TxFailure": "41.75%",
      "TxPlainte": "0.1%",
      "TxDesinscription": "0.17%"
    },
    ...
  }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

// With filter parameters
$query = [
    'id_mail' => "<id_mail>",
    'startStat' => '<startStat>',
    'endStat' => '<endStat>'
];
$response = $mk->get(Resources::STATISTICS, null, Resources::CAMPAIGNS, Resources::PROVIDER, $query);
print_r($response);

// Without filter parameters
$response = $mk->get(Resources::STATISTICS, null, Resources::CAMPAIGNS, Resources::PROVIDER);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint get statistics about your campaigns by providers.

HTTP Request

GET https://api.mailkitchen.com/v1/statistics/campaigns/provider

Query Parameters

Parameter Required Description
id_mail false Campaign's identifier in database
startStat false The start date whom you want to get statistics
endStat false The end date whom you want to get statistics

Response

The response is formatted in JSON with the status of API's request, you will get statistics by providers for your campaigns.

Field Description
NbEnvoi Number formatted of emails sent
NbOuverture Number formatted of emails opened
NbDestinataire Number of subscribers to whom emails have been sent
NbClic Number formatted of emails which recorded a click
NbOuvertureUnique Number of unique open emails
NbClicUnique Number of unique click emails
NbDesinscription Number of unsubscribe demand recorded
NbTransformation Number formatted of emails whom subscribers transformed with a tag included in emails
NbSoftBounce Number of emails which has temporarily refused
NbHardBounce Number of emails which has definitively refused
NbFailure Number of emails which has not sent
NbPlainte Number of emails which has received complaints
NbAbuse Number of emails which has been declared as spam by subscribers
NbBounceIndetermine Number of emails which has refused but we don't know the reason
NbEnAttente Number of emails are pending to send
NbBounce Number of total emails which has been refused
NbNonAbouti Number of emails not received by subscribers
NbReussiBrut Number of emails which has been received by subscribers
NbReussi Number formatted of emails which has been received by subscribers
NbNonReactif Number of emails which has been received but no activity from subscribers
NbCibleBrut Number of subscribers to whom emails have been sent
NbEnvoiBrut Number of emails sent
NbOuvertureBrut Number of emails opened
NbClicBrut Number of emails which recorded a click
NbTransformationBrut Number of emails whom subscribers transformed with a tag included in emails
TxEnAttente The rate of emails which are pending to send
TxReussiBrut The rate of emails which has been received
TxOuvertureBrut The rate of emails opened
TxOuverture The rate formatted of emails opened
TxOuvertureUnique The rate of emails opened
TxClic The rate formatted of emails which has recorded a click
TxClicBrut The rate of emails which has recorded a click
TxClicUnique The rate of emails which has recorded a single click
TxDesinscriptionBrut The rate of emails which has recorded an unsubscribe demand
TxEnvoie The rate of emails sent
TxTransformationBrut The rate of emails whom subscribers transformed with a tag included in emails
TxClic_Ouv The rate of clicks on opened emails
TxClicUnique_Ouv The rate of single click on opened emails
TxBounceBrut The rate of emails which has been refused
TxHardBounce The rate of emails which has been definitively refused
TxSoftBounce The rate of emails which has been temporarily refused
TxFailureBrut The rate of emails which has not been sent
TxPlainteBrut The rate of emails which has recorded complaints
TxBounceIndetermine The rate of emails which has refused but we don't know the reason
TxOuvertureUnique_Dest The rate of single open emails on subscribers
TxClicUnique_Dest The rate of single click on subscribers
TxDesinscription_Dest The rate of unsubscribe demand on subscribers
TxBounce_Dest The rate of emails which has not been received on subscribers
TxEnAttente_Dest The rate of emails which are pending on subscribers
TxNonReactif_Dest The rate of emails which has been received but no activity from subscribers on subscribers
NbCible Number formatted of subscribers to whom emails have been sent
TxReussi The rate formatted of emails which has been received
TxTransformation The rate formatted of emails whom subscribers transformed with a tag included in emails
TxBounce The rate formatted of emails which has been refused
TxFailure The rate formatted of emails which has not been sent
TxPlainte The rate formatted of emails which has recorded complaints
TxDesinscription The rate formatted of emails which has recorded an unsubscribe demand

Geolocation

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/statistics/campaigns/geolocation?id_mail=<campaignId>
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response

{
  "api": {
    "version": "1.0",
    "http_status_code": 200,
    "http_message": "200 (OK)"
  },
  "data": [
    {
      "open": 582,
      "clic": 42,
      "country": "FRANCE"
    },
    ...
  ]
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$query = [
    'id_mail' => "<id_mail>",
    'startStat' => '<startStat>',
    'endStat' => '<endStat>'
];
$response = $mk->get(Resources::STATISTICS, null, Resources::CAMPAIGNS, Resources::GEOLOCATION, $query);
print_r($response);

// the response is an array formatted like JSON response for cURL language
?>

This endpoint allows you to have details about activities of campaigns by geolocation.

HTTP Request

GET https://api.mailkitchen.com/v1/statistics/campaigns/geolocation?id_mail=<campaignId>

Query Parameters

Parameter Required Description
id_mail true Campaign's identifier in database
startStat false The start date whom you want to get statistics
endStat false The end date whom you want to get statistics

Response

The response is formatted in JSON with the status of API's request, the statistics by geolocation for campaigns.

Field Description
open The number of open emails in specific geolocation
clic The number of clicks in emails in specific geolocation
country The name of the geolocation where activities has been recorded

Client

## API Endpoint
curl -X GET https://api.mailkitchen.com/v1/statistics/campaigns/client?id_mail=<campaignId>
    -H 'Authorization: Bearer <token>'
    -H 'Content-Type: application/json'

## JSON Response
{
  "api": {
    "version": "1.0",
    "http_status_code": 200,
    "http_message": "200 (OK)"
  },
  "data": {
    "ua": [
      {
        "os": "Windows",
        "os_version": "10",
        "browser": "Firefox",
        "browser_version": "75",
        "webmail": "Other",
        "value": 18
      },
      ...
    ],
    "total": {
      "value": 1510
    }
  }
}
<?php
require 'vendor/autoload.php';
use Mailkitchen\Resources;

CONST API_KEY = '<api_key>';
CONST API_SECRET_KEY = '<api_secret_key>';

$mk = new \Mailkitchen\Client(['api_key' => API_KEY , 'api_secret_key' => API_SECRET_KEY]);

$query = [
    'id_mail' => "<id_mail>",
    'startStat' => '<startStat>',
    'endStat' => '<endStat>'
];
$response = $mk->get(Resources::STATISTICS, null, Resources::CAMPAIGNS, Resources::GEOLOCATION, $query);
print_r($response);

?>

This endpoint allows you to get information about client software used by your subscribers for your campaigns.

HTTP Request

GET https://api.mailkitchen.com/v1/statistics/campaigns/client?id_mail=<campaignId>

Query Parameters

Parameter Required Description
id_mail true Campaign's identifier in database
startStat false The start date whom you want to get statistics
endStat false The end date whom you want to get statistics

Response

The response is formatted in JSON with the status of API's request. The statistics about client software used by subscribers for your campaigns are given here.

Errors

In this section, you will find all errors returned by MailKitchen API. The following errors code are :

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Invalid Token.
403 Forbidden -- You have not access to this.
404 Not Found -- Bad call, please check the URL.
429 Too Many Requests -- You're requesting too many times! Slow down!
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.