eMailChef Public API

Version 1.3 2023-02-24

This document contains information about eMailChef’s public API. Please report bugs to: support@emailchef.com

Getting started

Data interchange format

For the most part (and where not otherwise explicit) eMailChef’s API uses JSON as the data format of choice when it comes to request and response bodies.

Accessing resources

Authorization to access a user’s resource is granted to clients provided they set a authkey header into their request, valued with the proper authentication key issued by eMailChef servers. The authentication key is user-based and it is issued by eMailChef servers upon successful user’s email address + password challenge, performed by means of appropriate request.

As an example, such header should look like what follows:

authkey: 724ee2fef00ffdc91c9b6cff40a9a122a2e7e77d

Error scenarios while accessing resources

1. Unauthorized

Whenever the authentication key is invalid or missing, any API request towards eMailChef servers will fail with the status shown aside.

Response to unauthorized request:

HTTP Status code: 401

Response body: Unauthorized

NOTE: It’s important to remember that the response message is given as plain text in this case.

2. Resource not found

Whenever a resource’s instance is requested, but it reveals to be outside of client’s scope (i.e.: either inexistent or not belonging to), such request will fail with the following status:

HTTP Status code: 404

Response body:

{ "status": "ERROR", "message": "resource_not_found" }

This does not apply to resource collections where, under the same conditions, an empty array ([]) is returned.

The authkey value in the response has to be used as a custom header for all requests towards eMailChef’s API.

Request endpoint:

POST https://app.emailchef.com/api/login HTTP/1.1

Request headers:

Content-Type: application/json; charset=utf-8

Request body:

{
    "username":"user.email@example.com",
    "password":"Th3Passw0rd"
}

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

Response body (successful authentication):

{
    "authkey":"3b205f8f12c91d3f937cf87759719cf6f268e5af",
    "message":"login OK"
}

Response body (unsuccessful authentication):

{
    "message":"Credentials wrong"
}

Meta Resources

This section documents those resources which represent a pre-requirement and are necessary for higher level resources to be set and given and for functionalities in order to work properly.

Application

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/meta/application HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "mode":"production",
   "hide_poor_growth_stats":true,
   "debug":false,
   "avangate":{
      "merchant":"NURAXISX",
      "confirmUrl":"https:\/\/app.emailchef.com\/customer\/purchase-completed",
      "shopUrl":"https:\/\/app.emailchef.com\/build\/#\/settings?section=my_account",
      "test":false
   }
}

Appconfig

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/appconfig/appconfig?lang=en HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "supported_languages":[
      "en",
      "it",
      "es",
      "de"
   ],
   "fallback_language":"en"
}

I18N

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/i18n/main_app/:lang_code HTTP/1.1

lang_code parameter can be one of the supported_languages collection, as returned by appconfig call.

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{  
   "emailchef":"eMailChef",
   "emailchef_title":"eMailChef - Kitchen",
   "dashboard":"dashboard",
   "copyright":"Delivery Tech Corp. 4411 Morena Blvd #230 San Diego, C2117.",
   "app_description":"eMailChef is the easiest-to-use email marketing service in the world..:",
   "dummy_mode":"demo mode",
   "welcome":"Welcome",
   "hi":"hi",
   "yes":"Yes"
}

Language names

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/meta/languagenames HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

[
   {
      "code":"en",
      "nativeName":"English"
   },
   {
      "code":"de",
      "nativeName":"Deutsch"
   },
   {
      "code":"it",
      "nativeName":"Italiano"
   },
   {
      "code":"es",
      "nativeName":"espa\u00f1ol, castellano"
   }
]

Policies

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/meta/policies/:policy_type HTTP/1.1

policy_type parameter can be one of the following:

safe: policies describing the most conservative account permissions
standard: policies describing normal account permissions
premium: policies describing advanced account permissions

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "status":"OK",
   "safe":{
      "admin_resubscribe":false,
      "global_unsubscribe":true,
      "contact_resubscribe":true,
      "single_optin":false,
      "allow_sending_without_can_spam_tags":false,
      "warn_before_sending_without_can_spam_tags":true
   }
}

Preferences

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/preferences/current HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "portlets":[
      "help_short",
      "design_your_campaign",
      "signup_form",
      "sent_campaign_summary",
      "account_policy",
      "account_summary",
      "draft_campaign_summary"
   ],
   "id":"187",
   "is_pristine":false,
   "contacts_count":"1",
   "sent_campaigns_count":"2"
}

Segments

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/meta/segments HTTP/1.1

Request headers:

authkey: <your_authentication_key>

NOTE: The response body shown here aside is just a convenient subset of the real whole response.

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "comparables":[
      {
         "comparable_id":"1",
         "name":"SUB_DATE",
         "type_id":"3",
         "type_name":"date"
      },
      {
         "comparable_id":"2",
         "name":"SUB_TYPE",
         "type_id":"5",
         "type_name":"select"
      },
      {
         "comparable_id":"3",
         "name":"LAST_NL_DATE",
         "type_id":"3",
         "type_name":"date"
      },
      {
         "comparable_id":"4",
         "name":"LAST_OPEN_DATE",
         "type_id":"3",
         "type_name":"date"
      },
      {
         "comparable_id":"5",
         "name":"LAST_CLICK_DATE",
         "type_id":"3",
         "type_name":"date"
      },
      {
         "comparable_id":"6",
         "name":"EVENT_OPEN",
         "type_id":"4",
         "type_name":"boolean"
      },
      {
         "comparable_id":"7",
         "name":"EVENT_CLICK",
         "type_id":"4",
         "type_name":"boolean"
      }
   ],
   "comparators_types":[
      {
         "comparator_id":1,
         "type_id":1
      },
      {
         "comparator_id":1,
         "type_id":2
      },
      {
         "comparator_id":1,
         "type_id":5
      },
      {
         "comparator_id":1,
         "type_id":6
      },
      {
         "comparator_id":1,
         "type_id":7
      },
      {
         "comparator_id":1,
         "type_id":8
      },
      {
         "comparator_id":1,
         "type_id":9
      },
      {
         "comparator_id":2,
         "type_id":1
      },
      {
         "comparator_id":2,
         "type_id":2
      },
      {
         "comparator_id":2,
         "type_id":5
      },
      {
         "comparator_id":2,
         "type_id":6
      },
      {
         "comparator_id":2,
         "type_id":7
      },
      {
         "comparator_id":2,
         "type_id":8
      },
      {
         "comparator_id":2,
         "type_id":9
      },
      {
         "comparator_id":3,
         "type_id":1
      },
      {
         "comparator_id":3,
         "type_id":5
      },
      {
         "comparator_id":3,
         "type_id":9
      },
      {
         "comparator_id":4,
         "type_id":1
      },
      {
         "comparator_id":4,
         "type_id":5
      },
      {
         "comparator_id":4,
         "type_id":9
      },
      {
         "comparator_id":5,
         "type_id":1
      },
      {
         "comparator_id":5,
         "type_id":5
      },
      {
         "comparator_id":5,
         "type_id":9
      },
      {
         "comparator_id":6,
         "type_id":1
      },
      {
         "comparator_id":6,
         "type_id":5
      },
      {
         "comparator_id":6,
         "type_id":9
      },
      {
         "comparator_id":7,
         "type_id":1
      },
      {
         "comparator_id":7,
         "type_id":5
      },
      {
         "comparator_id":7,
         "type_id":9
      },
      {
         "comparator_id":8,
         "type_id":1
      },
      {
         "comparator_id":8,
         "type_id":5
      },
      {
         "comparator_id":8,
         "type_id":9
      },
      {
         "comparator_id":9,
         "type_id":1
      },
      {
         "comparator_id":9,
         "type_id":5
      },
      {
         "comparator_id":9,
         "type_id":9
      },
      {
         "comparator_id":10,
         "type_id":1
      },
      {
         "comparator_id":10,
         "type_id":5
      },
      {
         "comparator_id":10,
         "type_id":9
      },
      {
         "comparator_id":11,
         "type_id":3
      },
      {
         "comparator_id":12,
         "type_id":3
      },
      {
         "comparator_id":13,
         "type_id":3
      },
      {
         "comparator_id":14,
         "type_id":4
      },
      {
         "comparator_id":15,
         "type_id":2
      },
      {
         "comparator_id":16,
         "type_id":2
      },
      {
         "comparator_id":17,
         "type_id":3
      }
   ],
   "comparators":[
      {
         "id":1,
         "name":"IS",
         "type_name":"text",
         "type_id":1
      },
      {
         "id":2,
         "name":"IS_NOT",
         "type_name":"text",
         "type_id":1
      },
      {
         "id":3,
         "name":"CONTAIN",
         "type_name":"text",
         "type_id":1
      },
      {
         "id":4,
         "name":"NOT_CONTAIN",
         "type_name":"text",
         "type_id":1
      },
      {
         "id":5,
         "name":"IS_PROVIDED",
         "type_name":"text",
         "type_id":1
      },
      {
         "id":6,
         "name":"IS_NOT_PROVIDED",
         "type_name":"text",
         "type_id":1
      },
      {
         "id":7,
         "name":"START_WITH",
         "type_name":"text",
         "type_id":1
      },
      {
         "id":8,
         "name":"END_WITH",
         "type_name":"text",
         "type_id":1
      },
      {
         "id":9,
         "name":"NOT_START_WITH",
         "type_name":"text",
         "type_id":1
      },
      {
         "id":10,
         "name":"NOT_END_WITH",
         "type_name":"text",
         "type_id":1
      },
      {
         "id":11,
         "name":"IS_AFTER",
         "type_name":"date",
         "type_id":3
      },
      {
         "id":12,
         "name":"IS_BEFORE",
         "type_name":"date",
         "type_id":3
      },
      {
         "id":13,
         "name":"IS_DATE",
         "type_name":"date",
         "type_id":3
      },
      {
         "id":14,
         "name":"HAPPENED",
         "type_name":"boolean",
         "type_id":4
      },
      {
         "id":15,
         "name":"IS_LESS_THEN",
         "type_name":"number",
         "type_id":2
      },
      {
         "id":16,
         "name":"IS_GREATER_THEN",
         "type_name":"number",
         "type_id":2
      },
      {
         "id":17,
         "name":"IS_NOT_DATE",
         "type_name":"date",
         "type_id":3
      }
   ]
}

Userlog - get collection

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/userlog?limit=10&offset=0 HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

[
   {
      "id":"3293",
      "ts":"2015-10-22 09:16:03",
      "name":"CampaignSchedule",
      "ipaddr":"93.34.48.147",
      "session_id":"a71ccb135875d8b73a493f6951bba0fc0a5493b3",
      "useragent":"1",
      "params":{
         "campaign_id":"1352",
         "campaign_name":"Nome campagna 2015-10-22 09:13:48",
         "schedule_time":"2015-10-22 11:20:00"
      }
   },
   {
      "id":"3292",
      "ts":"2015-10-22 09:16:03",
      "name":"CampaignEdit",
      "ipaddr":"93.34.48.147",
      "session_id":"a71ccb135875d8b73a493f6951bba0fc0a5493b3",
      "useragent":"1",
      "params":{
         "campaign_id":"1352",
         "campaign_name":"Nome campagna 2015-10-22 09:13:48"
      }
   },
   ...
]

Userlog - get count

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/userlog/count HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{ 
    "recnum": "23" 
}

Plans - get collection

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/plans?billing_cycle=:billing_cycle HTTP/1.1

This request does not require authentication

billing_cycle parameter is optional and can be one of the following:
- month - [DEFAULT] only plans with monthly billing cycle are returned, together with the free plan
- year - only plans with yearly billing cycle are returned

Request headers:

none

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

[
   {
      "id":"1",
      "default":"1",
      "prod_ref":null,
      "name":"APPETIZER",
      "send_limit":"12000",
      "max_contacts":"2000",
      "limit_interval":"month",
      "ord":"1",
      "amount":"FREE",
      "currency_symbol":null,
      "currency_code":null
   },
   {
      "id":"9",
      "default":"0",
      "prod_ref":"4634640",
      "name":"BREAKFAST",
      "send_limit":"2147483647",
      "max_contacts":"1000",
      "limit_interval":"month",
      "ord":"2",
      "amount":"10",
      "currency_symbol":"$",
      "currency_code":"USD"
   },
   ...
]

Plans - get instance

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/plans/:plan_id HTTP/1.1

plan_id parameter is the id of the plan to retrieve

This request does not require authentication

Request headers:

none

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
    "id":"1",
    "default":"1",
    "prod_ref":null,
    "name":"APPETIZER",
    "send_limit":"12000",
    "max_contacts":"2000",
    "limit_interval":"month",
    "ord":"1",
    "amount":"FREE",
    "currency_symbol":null,
    "currency_code":null
}

Packages - get collection

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/packages HTTP/1.1

This request does not require authentication

Request headers:

none

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

[
    {
        "id": "1",
        "credits": "2000",
        "ord": "1",
        "amount": "30",
        "currency_symbol": "$",
        "currency_code": "USD"
    },
    {
        "id": "2",
        "credits": "5000",
        "ord": "2",
        "amount": "50",
        "currency_symbol": "$",
        "currency_code": "USD"
    },
    {
        "id": "3",
        "credits": "10000",
        "ord": "3",
        "amount": "90",
        "currency_symbol": "$",
        "currency_code": "USD"
    },
    ...
]

Packages - get instance

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/packages/:package_id HTTP/1.1

package_id parameter is the id of the package to retrieve

This request does not require authentication

Request headers:

none

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
    "id": "2",
    "credits": "5000",
    "ord": "2",
    "amount": "50",
    "currency_symbol": "$",
    "currency_code": "USD"
}

Senders - get collection

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/senders HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

[
  {
    "id": "784",
    "name": "John Smith",
    "user": "yourmailbox",
    "domain": "gmail.com",
    "status": "VERIFIED",
    "email": "yourmailbox@gmail.com",
    "default_sender": "1",
    "address_1": "Address 1",
    "address_2": null,
    "business": "Your Company",
    "city": "Boston, MA",
    "postal_code": "91132",
    "country": "US"
  },
  ...
]

Timezones - get collection

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/meta/timezones HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

[
  {
    "id": "1",
    "offset": "+00:00",
    "name": "Casablanca"
  },
  {
    "id": "5",
    "offset": "+01:00",
    "name": "Amsterdam,Berlin,Bern,Rome,Stock"
  },
  {
    "id": "11",
    "offset": "+02:00",
    "name": "Athens,Bucharest"
  },
  {
    "id": "20",
    "offset": "+03:00",
    "name": "Amman"
  },
  {
    "id": "25",
    "offset": "+03:30",
    "name": "Tehran"
  },
  {
    "id": "26",
    "offset": "+04:00",
    "name": "Abu Dhabi,Muscat"
  },
  {
    "id": "32",
    "offset": "+04:30",
    "name": "Kabul"
  },
  {
    "id": "33",
    "offset": "+05:00",
    "name": "Islamabad,Karachi"
  },
  {
    "id": "35",
    "offset": "+05:30",
    "name": "Chennai,Kolkata,Mumbai,New Delhi"
  },
  {
    "id": "37",
    "offset": "+05:45",
    "name": "Kathmandu"
  },
  {
    "id": "38",
    "offset": "+06:00",
    "name": "Astana"
  },
  {
    "id": "41",
    "offset": "+06:30",
    "name": "Yangon (Rangoon,"
  },
  {
    "id": "42",
    "offset": "+07:00",
    "name": "Bangkok,Hanoi,Jakarta"
  },
  {
    "id": "44",
    "offset": "+08:00",
    "name": "Beijing,Chongqing,Hong Kong,Urum"
  },
  {
    "id": "50",
    "offset": "+09:00",
    "name": "Irkutsk"
  },
  {
    "id": "53",
    "offset": "+09:30",
    "name": "Adelaide"
  },
  {
    "id": "55",
    "offset": "+10:00",
    "name": "Brisbane"
  },
  {
    "id": "60",
    "offset": "+11:00",
    "name": "Solomon Is.,New Caledonia"
  },
  {
    "id": "62",
    "offset": "+12:00",
    "name": "Auckland,Wellington"
  },
  {
    "id": "67",
    "offset": "+13:00",
    "name": "Nukualof"
  },
  {
    "id": "69",
    "offset": "-01:00",
    "name": "Azores"
  },
  {
    "id": "71",
    "offset": "-02:00",
    "name": "Coordinated Universal Time-02"
  },
  {
    "id": "73",
    "offset": "-03:00",
    "name": "Brasilia"
  },
  {
    "id": "79",
    "offset": "-03:30",
    "name": "Newfoundland"
  },
  {
    "id": "80",
    "offset": "-04:00",
    "name": "Asuncion"
  },
  {
    "id": "85",
    "offset": "-04:30",
    "name": "Caracas"
  },
  {
    "id": "86",
    "offset": "-05:00",
    "name": "Bogota,Lima,Quito"
  },
  {
    "id": "89",
    "offset": "-06:00",
    "name": "Central America"
  },
  {
    "id": "93",
    "offset": "-07:00",
    "name": "Arizona"
  },
  {
    "id": "96",
    "offset": "-08:00",
    "name": "Baja California"
  },
  {
    "id": "98",
    "offset": "-09:00",
    "name": "Alaska"
  },
  {
    "id": "99",
    "offset": "-10:00",
    "name": "Hawaii"
  },
  {
    "id": "100",
    "offset": "-11:00",
    "name": "Coordinated Universal Time-11"
  },
  {
    "id": "101",
    "offset": "-12:00",
    "name": "International Date Line West"
  }
]

Resources

This section documents all of those resources which are dedicated to users in order to perform operations within eMailChef.

Account

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/accounts/current HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "id":"785510",
   "email":"name+908070@mycompany.com",
   "lang":"it",
   "status":"ACTIVE",
   "whiteLabeled":"0",
   "relayBounces":"0",
   "billing_clientid":null,
   "parentid":null,
   "bounceSuppress":"0",
   "domain":null,
   "allowWebsiteAccess":"0",
   "total":"0",
   "bounce":"0",
   "complaints":"0",
   "last_update":null,
   "mode":"safe",
   "logo_url":null,
   "dummy":"0",
   "beta_tester":"1",
   "subscribers":"1",
   "s_token":"7o226163636s756r745s6964223n22373835353130227q"
}

Account infos - get instance

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/account_infos/785510 HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "billingInfo":{
      "firstname":"Lorenzo",
      "lastname":"Calcaterra",
      "business":"Sleepers Ltd.",
      "address_1":"Hell's Kitchen",
      "address_2":"",
      "city":"New York",
      "postal_code":"10101",
      "country":"US",
      "region":"NY",
      "phone_number":"23233232",
      "vat_info":"",
      "website":"http://www.sleepersltd.com"
   }
}

Account infos - update instance

Request endpoint:

POST https://app.emailchef.com/apps/api/v1/account_infos HTTP/1.1

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Request body:

{
   "instance_in":{
      "firstname":"Lorenzo",
      "lastname":"Calcaterra",
      "business":"Sleepers Ltd.",
      "address_1":"Hell's Kitchen",
      "address_2":"",
      "city":"New York",
      "postal_code":"101010",
      "country":"US",
      "region":"NY",
      "phone_number":"23233232",
      "vat_info":"",
      "website":"http://www.sleepersltd.com"
   }
}

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{  
   "status":"OK"
}

Subscription

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/subscriptions/current HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
    "account_id": "785618",
    "type": "PAYG",
    "simple_send_count": "0",
    "send_count": null,
    "credits_count": "300",
    "credits_count_ref": "300",
    "id": "237",
    "plan_id": null,
    "plan_expiration": "9999-12-31",
    "c_date": "2016-02-02",
    "expired": "0",
    "last_used": null,
    "active": "1",
    "license_code": "",
    "pending_payment": "0",
    "pending_payment_last_update": null,
    "prod_ref": null,
    "send_limit": null,
    "max_contacts": null,
    "plan_name": null,
    "limit_interval": null,
    "plan_ord": null
}

Lists - get collection

Returns a collection of lists belonging to the current account.

A list is a container for contacts.

–

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/lists?limit=:limit&offset=:offset&orderby=:orderby&ordertype=:ordertype HTTP/1.1

limit parameter is the number of results to return (for a single page), default is 10
offset parameter is the number of results to skip prior to start considering results to return, default is 0
orderby parameter represents the results sorting criteria, and can be one of:
- cd : creation date (default)
- n : name
ordertype parameter represents the sorting type, and can be one of:
- a : ascending
- d : descending (default)

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

[  
   {  
      "name":"Test List Zero",
      "id":"487",
      "description":"First list to play with",
      "active":"26",
      "segments":"0",
      "unsubscribed":"0",
      "bounced":"0",
      "in_newsletter":"0",
      "date":"2015-10-08 10:22:09"
   }, 
   {  
      "name":"Test List One",
      "id":"488",
      "description":"Second list to play with",
      "active":"20",
      "segments":"2",
      "unsubscribed":"0",
      "bounced":"0",
      "in_newsletter":"0",
      "date":"2015-10-09 12:22:09"
   },
   ...
]

Lists - get instance

Returns a single list’s general data.

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/lists/:id HTTP/1.1

id parameter is the list id

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{  
   "name":"Test List Zero",
   "description":"First list to play with",
   "sender_name":null,
   "sender_email":null,
   "creation_date":"2015-10-08 10:22:09"
}

Lists - get stats

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/lists/487/stats?start_date=:start_date&end_date=:end_date HTTP/1.1

start_date parameter is a date formatted as ‘YYYY-MM-DD’, or -1 meant as 'from the very beginning’
end_date parameter is a date formatted as 'YYYY-MM-DD’, or -1 meant as 'until the very end’

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{  
   "total_list":[  
      {  
         "date":"2015-10-08",
         "total":26
      }
   ],
   "daily_delta_list":[  
      {  
         "date":"2015-10-08",
         "daily_delta":"26"
      }
   ],
   "start_date":"2015-10-08",
   "last_date":"2015-10-08"
}

Lists - unsubscribe

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/lists/:list_id/unsubscribe?contact_id=:contact_id&list_id=:list_id HTTP/1.1

contact_id parameter is the id of the contact to unsubscribe

list_id parameter is the id of the list from which the contact has to be unsubscribed

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "status":"OK",
   "message":"recipient_unsubscribed"
}

Lists - create instance

Request endpoint:

POST https://app.emailchef.com/apps/api/v1/lists HTTP/1.1

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Request body:

{
    "instance_in":{
        "list_name":"Test List 1001",
        "list_description":"Ultimate List to be defined"  
   }
}

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "status":"OK",
   "list_id":"510"
}

Lists - update instance

Request endpoint:

PUT https://app.emailchef.com/apps/api/v1/lists/:list_id HTTP/1.1

list_id parameter represents the id of the resource to be updated

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Request body:

{
    "instance_in":{
        "list_name":"Test List Zero",
        "list_description":"Ultimate List to be deleted"  
   }
}

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "status":"OK",
   "list_id":"510"
}

Lists - delete instance

Request endpoint:

DELETE https://app.emailchef.com/apps/api/v1/lists/:list_id HTTP/1.1

list_id parameter represents the id of the resource to be deleted

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Request body:

{
    "instance_in":{
        "list_name":"Test List Zero",
        "list_description":"Ultimate List to be deleted"  
   }
}

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Contacts - get count

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/lists/:list_id/contacts/count HTTP/1.1

list_id parameter is the id of the list which the counted contacts belong to.

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{  
   "active":"26",
   "unsubscribed":"0",
   "bounced":"0",
   "reported":"0"
}

Contacts - get collection

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/contacts?status=:status&limit=:limit&list_id=:list_id&offset=:offset&orderby=:orderby&ordertype=:ordertype HTTP/1.1

status parameter can be one of the following:
- ACTIVE
- UNSUBSCRIBED
- BOUNCED
- REPORTED
list_id parameter is the id of the list from which contacts are fetched
limit parameter is the number of results to return (for a single page), default is 10
offset parameter is the number of results to skip prior to start considering results to return, default is 0
orderby parameter represents the results sorting criteria, and can be one of:
- e : email
- n : name
- ab : added_by
- at : addition_time (default)
- s : status
ordertype parameter represents the sorting type, and can be one of:
- a : ascending
- d : descending (default)

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

[  
   {  
      "id":"4",
      "email":"blackhole3@blackhole.turbo-smtp.com",
      "added_by":"ADMIN",
      "subscribed":"2015-10-08 10:23:24",
      "name":"black3 hole3 ",
      "event_time":null
   },
   {  
      "id":"2",
      "email":"blackhole1@blackhole.turbo-smtp.com",
      "added_by":"ADMIN",
      "subscribed":"2015-10-08 10:23:24",
      "name":"black1 hole1 ",
      "event_time":null
   },
   ...
]

Contacts - get instance

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/contacts/:contact_id?list_id=:list_id HTTP/1.1

contact_id parameter is the id of the contact to fetch
list_id parameter is the id of the list which :contact_id belongs to

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{  
   "status":"ACTIVE",
   "email":"blackhole6@blackhole.turbo-smtp.com",
   "firstname":"black6 hole6",
   "lastname":null,
   "ip":null,
   "added_by":"ADMIN",
   "addition_time":"2015-10-08 10:23:24",
   "customFields":[  

   ]
}

Contacts - create instance

Request endpoint:

POST https://app.emailchef.com/apps/api/v1/contacts HTTP/1.1

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Request body:

{
   "instance_in":{
      "list_id":"<list_id>",
      "status":"<status>",
      "email":"<email_address>",
      "firstname":"<first_name>",
      "lastname":"<last_name>",
      "custom_fields":{
         "0":{
            "id":"<custom_field_id>",
            "list_id":"<list_id>",
            "name":"<field_name>",
            "type_id":"<field_type_id>",
            "place_holder":"<field_placeholder>",
            "options":"<field_options_if_type_is_select>",
            "default_value":"<field_default_value>",
            "admin_only":"0",
            "ord":null,
            "data_type":"<field_data_type>",
            "value":"<field_value>"
         }
      },
      "mode":"ADMIN"
   }
}

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

NOTE: If contact is already present into the list, contact_added_to_list key is set to false

{
   "contact_added_to_list":true, 
   "contact_id":"709029",
   "contact_status":"ACTIVE"
}

Error for unauthorized access to list resource / list resource not existent:

{
   "status":"ERROR",
   "message":"unauthorized_request"
}

Contacts - update instance

Request endpoint:

PUT https://app.emailchef.com/apps/api/v1/contacts/:contact_id HTTP/1.1

contact_id parameter i the id of the contact to update

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Request body:

{
   "instance_in":{
      "list_id":"<list_id>",
      "status":"<contact_status>",
      "firstname":"<contact_first_name>",
      "lastname":"<contact_last_name>",
      "custom_fields":{
         "0":{
            "data_type":"<field_data_type>",
            "id":"<field_id>",
            "name":"<field_name>",
            "options":"<field_options_if_type_is_select>",
            "place_holder":"tablet",
            "value":"1"
         }
      },
      "mode":"ADMIN"
   }
}

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{  
   "status":"OK",
   "contact_id":"4"
}

Predefined Fields - get collection

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/predefinedfields HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

[
    {
        "id": "-1",
        "name": "email",
        "type_id": "9",
        "place_holder": "email",
        "reference": "CONCAT(`contacts`.`user`, '@', `contacts`.`domain`)",
        "mandatory": "0",
        "data_type": "email"
    },
    {
        "id": "-2",
        "name": "first_name",
        "type_id": "1",
        "place_holder": "first_name",
        "reference": "`lc`.`firstname`",
        "mandatory": "0",
        "data_type": "text"
    },
    {
        "id": "-3",
        "name": "last_name",
        "type_id": "1",
        "place_holder": "last_name",
        "reference": "`lc`.`lastname`",
        "mandatory": "0",
        "data_type": "text"
    }
]

Custom Fields - get collection

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/lists/:list_id/customfields HTTP/1.1

list_id parameter is the id of the list from which custom fields have to be fetched:

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

[
    {
        "id": "1189",
        "list_id": "251338",
        "name": "MyNumber1",
        "type_id": "2",
        "place_holder": "mynumber1",
        "options": null,
        "default_value": "9999",
        "admin_only": "0",
        "ord": "1",
        "data_type": "number"
    },
    {
        "id": "1188",
        "list_id": "251338",
        "name": "MyText1",
        "type_id": "1",
        "place_holder": "mytext1",
        "options": null,
        "default_value": "Hello",
        "admin_only": "0",
        "ord": "2",
        "data_type": "text"
    },
    {
        "id": "1191",
        "list_id": "251338",
        "name": "MyYesNo1",
        "type_id": "4",
        "place_holder": "myyesno1",
        "options": null,
        "default_value": "1",
        "admin_only": "0",
        "ord": "3",
        "data_type": "boolean"
    },
    {
        "id": "1192",
        "list_id": "251338",
        "name": "MySelect1",
        "type_id": "5",
        "place_holder": "myselect1",
        "options": [
            {
                "text": "Ferrari"
            },
            {
                "text": "Lamborghini"
            },
            {
                "text": "Porsche"
            },
            {
                "text": "Mercedes"
            },
            {
                "text": "Audi"
            }
        ],
        "default_value": "Porsche",
        "admin_only": "0",
        "ord": "4",
        "data_type": "select"
    },
    {
        "id": "1208",
        "list_id": "251338",
        "name": "Tablet",
        "type_id": "4",
        "place_holder": "tablet",
        "options": null,
        "default_value": "1",
        "admin_only": "0",
        "ord": "6",
        "data_type": "boolean"
    },
    {
        "id": "1209",
        "list_id": "251338",
        "name": "Smartphone2",
        "type_id": "4",
        "place_holder": "smartphone2",
        "options": null,
        "default_value": "1",
        "admin_only": "0",
        "ord": "7",
        "data_type": "boolean"
    },
    {
        "id": "1212",
        "list_id": "251338",
        "name": "Smartphone4",
        "type_id": "1",
        "place_holder": "smartphone4",
        "options": null,
        "default_value": "1",
        "admin_only": "0",
        "ord": "8",
        "data_type": "text"
    }
]

Custom Fields - get instance

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/customfields/:field_id HTTP/1.1

field_id parameter is the id of the field to get

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{  
   "id":"361",
   "list_id":"487",
   "name":"Smartphone",
   "type_id":"4",
   "place_holder":"smartphone",
   "options":null,
   "default_value":"1",
   "admin_only":"0",
   "ord":null,
   "data_type":"boolean"
}

Custom Fields - get count

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/lists/:list_id/customfields/count HTTP/1.1

list_id parameter is the id of the list of which the custom fields have to be counted

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{  
   "totalcount": "8"
}

Custom Fields - create instance

Request endpoint:

POST https://app.emailchef.com/apps/api/v1/lists/:list_id/customfields HTTP/1.1

list_id parameter is the id of the list under which the new custom field has to be created

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Request body:

{  
   "instance_in":{  
      "data_type":"boolean",
      "name":"Smartphone",
      "place_holder":"smartphone",
      "default_value":"1"
   }
}

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{  
   "status":"OK",
   "custom_field_id":"361"
}

Custom Fields - update instance

Request endpoint:

PUT https://app.emailchef.com/apps/api/v1/lists/customfields/:field_id HTTP/1.1

field_id parameter is the id of the field to update

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Request body:

{  
   "instance_in":{  
      "list_id":"487",
      "name":"Tablet",
      "type_id":"4",
      "place_holder":"tablet",
      "options":null,
      "default_value":"1",
      "admin_only":"0",
      "ord":null,
      "data_type":"boolean"
   }
}

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{  
   "status":"OK",
   "custom_field_id":"361"
}

Custom Fields - delete instance

Request endpoint:

DELETE https://app.emailchef.com/apps/api/v1/customfields/:field_id HTTP/1.1

field_id parameter is the id of the field to delete

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{  
   "status":"OK"
}

Blockings - get collection

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/blockings?query_string=&limit=10&offset=0 HTTP/1.1

query_string parameter is a string to be searched into blocked contacts; all matching contacts will be returned
limit parameter is the number of results to return (for a single page), default is 10
offset parameter is the number of results to skip prior to start considering results to return, default is 0

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

NOTE: type key can be MANUAL, UNSUBSCRIBE or COMPLAINT

[
   {
      "email":"fzancan+404@gmail.com",
      "type":"MANUAL"
   },
   ...
]

Blockings - get count

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/blockings/count?query_string= HTTP/1.1

query_string parameter is a string to be searched into blocked contacts; all matching contacts will be counted

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "totalcount":"100"
}

Blockings - create instance

Request endpoint:

POST https://app.emailchef.com/apps/api/v1/blockings?email=:email&type=:type HTTP/1.1

email parameter is the email address to block
type parameter is the type of the block to apply. Can be one of:
- MANUAL
- UNSUBSCRIBED
- COMPLAINT

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "status":"OK",
   "address":"fzancan+404@gmail.com"
}

Blockings - delete instance

Request endpoint:

DELETE https://app.emailchef.com/apps/api/v1/blockings/:email HTTP/1.1

email parameter is the email to be removed from blockings

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "status":"OK",
   "address":"fzancan+404@gmail.com"
}

Import Tasks - get collection

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/importtasks HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

[
    {
        "id": "4342",
        "list_id": "251397",
        "creation_time": "2015-12-10 14:49:42",
        "error_message": null,
        "imported_success": "2",
        "imported_fail": "0",
        "imported_updated": "0",
        "last_updated": "2015-12-10 15:01:37",
        "progress": "100",
        "status": "COMPLETE",
        "uploaded_file_name": "copy_and_paste",
        "list_name": "Hello list 1",
        "notification_link": null
    },
    {
        "id": "4331",
        "list_id": "251338",
        "creation_time": "2015-11-23 11:41:30",
        "error_message": null,
        "imported_success": "0",
        "imported_fail": "0",
        "imported_updated": "2",
        "last_updated": "2015-11-23 17:54:58",
        "progress": "100",
        "status": "COMPLETE",
        "uploaded_file_name": "/home/federico/newsletter/uploads/785558_1448278890.7521.CSV",
        "list_name": "Test List Zero",
        "notification_link": "http://2.40.99.44:28888"
    },
    {
        "id": "4330",
        "list_id": "251338",
        "creation_time": "2015-11-23 11:34:53",
        "error_message": null,
        "imported_success": "0",
        "imported_fail": "0",
        "imported_updated": "2",
        "last_updated": "2015-11-23 17:54:57",
        "progress": "100",
        "status": "COMPLETE",
        "uploaded_file_name": "/home/federico/newsletter/uploads/785558_1448278493.4033.CSV",
        "list_name": "Test List Zero",
        "notification_link": "http://2.40.99.44:28888"
    },
    {
        "id": "4328",
        "list_id": "251338",
        "creation_time": "2015-11-20 10:58:23",
        "error_message": null,
        "imported_success": "0",
        "imported_fail": "0",
        "imported_updated": "2",
        "last_updated": "2015-11-20 10:58:23",
        "progress": "100",
        "status": "COMPLETE",
        "uploaded_file_name": "/home/federico/newsletter/uploads/785558_1448017103.1501.CSV",
        "list_name": "Test List Zero",
        "notification_link": null
    },   ...
]

Import Tasks - get instance (a.k.a. “single task instant status”)

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/importtasks/:task_id HTTP/1.1

task_id parameter is the id of the task to be retrieved

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body (unfinished task):

{
    "id": "4331",
    "list_id": "251338",
    "status": "DISPATCHED",
    "error_message": null,
    "progress": "50",
    "imported": "4",
    "failed": "0",
    "updated": "5",
    "last_updated": "2015-11-23",
    "uploaded_file_name": "2015-11-23",
    "notification_link": "http://2.40.99.44:28888",
    "list_name": "Test List Zero"
}

Response body (finished task):

{
    "id": "4331",
    "list_id": "251338",
    "status": "COMPLETE",
    "error_message": null,
    "progress": "100",
    "imported": "13",
    "failed": "0",
    "updated": "5",
    "last_updated": "2015-11-23",
    "uploaded_file_name": "2015-11-23",
    "notification_link": "http://2.40.99.44:28888",
    "list_name": "Test List Zero"
}

Import Tasks - create instance (a.k.a. “import contacts”)

Request endpoint:

POST https://app.emailchef.com/apps/api/v1/lists/:list_id/import HTTP/1.1

list_id parameter is the id of the list into which new contacts provided y this request should be imported

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Request body:

{
   "instance_in":{
      "contacts":[
         [
            {
               "placeholder":"email",
               "value":"fzancan@gmail.com"
            },
            {
               "placeholder":"first_name",
               "value":"Federico"
            },
            {
               "placeholder":"last_name",
               "value":"Zancan"
            },
            {
               "placeholder":"telephone",
               "value":"0123456789"
            }
         ],
         [
            {
               "placeholder":"email",
               "value":"leonardo.perria@gmail.com"
            },
            {
               "placeholder":"first_name",
               "value":"Leonardo"
            },
            {
               "placeholder":"last_name",
               "value":"Perria"
            },
            {
               "placeholder":"telephone",
               "value":"0123456789"
            }
         ]
      ],
      "notification_link":"http://usersremotesite.net/notifications/endpoint"
   }
}

Just a few words upon the request body you can see here aside.

As you may have noticed, the request body is essentially made of 2 elements:

contacts
notification_link

Each entry (or “item”) in contacts will be made of a collection of placeholder/value couples. So the field is recognized by the specified placeholder. We picked this form instead of the more direct key/value pairs in order to avoid eventual unallowed characters in keys, due to possible system-meaningful characters (such as the dollar sign $) present in placeholders definitions which could screw up later request processing.

Plus, the request will optionally contain a notification_link, with a URL to a user’s remote endpoint ready to receive task termination notifications via HTTP POST method.

It falls under clients’s responsibility if the endpoint URL is wrong, or is somehow unreachable or not ready to receive POST notifications messages. Our process will make 1 and only 1 attempt to send terminal task notification.

If the remote server fails to catch it, the user will anyways conserve the ability to query import tasks status by the “get instance” call described above.

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "status":"OK",
   "id":"<new-task-id>",
   "validation_errors": [
      {
         "item_index": 12, 
         "message": "invalid_email_address"
      },
      ...
   ],
   "validation_warnings": []
}

The validation_errors and validation_warnings collections within the response body are made of sets of objects, each composed by an item_index / message couple. The item_index is the ordinal subscript of the original item within the contacts collection into the request body. The message attribute is a synthetic code-wise explanation of the ancountered problem.

Thus, the requesting client will be able to use the task id invoking the “get instance” endpoint in order to query import process status.

In case of validation errors/warnings absence, the validation_errors and / or the validation_warnings property will be an empty array ([]). Such arrays are provided as a clue for the API client in order to eventually let it grasp the reasons behind contacts import failures shown into the final operation report posted to the remote notification_url or non-blocking warning conditions at task preparation level.

If a notification_link is provided within the request, when the importer ends its job it will try to POST a final operations report to that URL.

Such final operations report structure is reported aside.

Final operations report:

{
   "successful":100,
   "failed":0,
   "new":84
}

Obviously, the formula:

(successful + failed) - new

gives a hint on how many contact updates there have been.

Segments - get collection

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/lists/:list_id/segments?limit=:limit&offset=:offset HTTP/1.1

limit parameter is the number of results to return (for a single page), default is 10
offset parameter is the number of results to skip prior to start considering results to return, default is 0

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

Response body:

[
   {
      "id":"98",
      "name":"Segment 1",
      "description":"This is a first segment",
      "match_count":"10",
      "total_count":"27",
      "last_refresh_time":"2015-10-26 08:48:26"
   },
   ...
]

Segments - get instance

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/lists/251338/segments/:segment_id HTTP/1.1

segment_id parameter is the id of the segment to retrieve

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "id":"792",
   "list_id":"251338",
   "logic":"AND",
   "condition_groups":[
      {
         "id":"2512",
         "logic":"AND",
         "conditions":[
            {
               "id":"2958",
               "field_id":"-1",
               "comparable_id":null,
               "comparator_id":"3",
               "value":"zancan"
            }
         ]
      }
   ],
   "name":"Segment 1",
   "description":"This is the first segment"
}

Segments - get count

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/lists/:list_id/segments/count? HTTP/1.1

list_id parameter is the id of the list whose segments have to be counted

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "totalcount":"10"
}

Segments - get contacts count for segment instance

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/segments/:segment_id/contacts/count HTTP/1.1

segment_id parameter is the id of the segment whose contacts have to be counted

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "match_count":"10",
   "total_count":"27"
}

Segments - create instance

Request endpoint:

POST https://app.emailchef.com/apps/api/v1/segments HTTP/1.1

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Request body:

{
   "instance_in":{
      "list_id":"487",
      "logic":"AND",
      "condition_groups":[
         {
            "logic":"OR",
            "conditions":[
               {
                  "field_id":"-1",
                  "name":"email",
                  "comparable_id":null,
                  "comparator_id":"3",
                  "value":"black"
               }
            ]
         }
      ],
      "name":"My Segment",
      "description":"The first segment to play with",
   }
}

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "status":"OK",
   "id":"99"
}

Segments - update instance

Request endpoint:

PUT https://app.emailchef.com/apps/api/v1/segments/:segment_id HTTP/1.1

segment_id parameter is the id of the segment to be updated

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Request body:

{
   "instance_in":{
      "list_id":"487",
      "logic":"AND",
      "condition_groups":[
         {
            "logic":"OR",
            "conditions":[
               {
                  "field_id":"-1",
                  "name":"email",
                  "comparable_id":null,
                  "comparator_id":"3",
                  "value":"black"
               }
            ]
         }
      ],
      "name":"My Segment",
      "description":"The first super segment to play with",
   }
}

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "status":"OK",
   "id":"99"
}

Segments - delete

Request endpoint:

DELETE https://app.emailchef.com/apps/api/v1/segments/:segment_id HTTP/1.1

segment_id parameter is the id of the segment to be deleted

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "status":"OK",
   "id":"100"
}

Campaigns - get count

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/campaigns/count HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
   "saved_draft_counter":"1",
   "sent_counter":"2",
   "scheduled_counter":"0",
   "archived_counter":"0",
   "failed_counter":"0"
}

Campaigns - get collection

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/campaigns?status=SCHEDULED&limit=10&offset=0&orderby=t&ordertype=d HTTP/1.1

GET https://app.emailchef.com/apps/api/v1/campaigns?status1=SENT&status2=SENDING&limit=10&offset=0&orderby=t&ordertype=d HTTP/1.1

The version with “status1” and “status2” parameters within the URI lets you obtain all campaigns matching 2 different statuses instead of just 1.

status, status1 and status2 parameters can be one of the following:
- DRAFT
- SCHEDULED
- SENDING
- SENT
- ARCHIVED
- FAILED
limit parameter is the number of results to return (for a single page), default is 10
offset parameter is the number of results to skip prior to start considering results to return, default is 0
orderby parameter can be one of the following:
- t : creation date
- name : list name
ordertype parameter can be one of the following:
- a : ascending
- d : descending

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

[
   {
      "id":"1327",
      "sender_id":"143",
      "name":"eMailChef New Campaign 2015-10-15 12:35:51",
      "date":"2015-10-15 10:35:53",
      "status":"SENT",
      "scheduled_time":"2015-10-22 14:40:00",
      "send_time":"2015-10-22 12:39:15",
      "recipients":"1",
      "queue_num":"1",
      "success_num":"1",
      "delivered":1,
      "unique_opened":1,
      "unique_clicked":0,
      "attempted":1
   },
   {
      "id":"1352",
      "sender_id":"143",
      "name":"New offers",
      "date":"2015-10-22 09:14:04",
      "status":"SENT",
      "scheduled_time":"2015-10-22 11:20:00",
      "send_time":"2015-10-22 09:20:02",
      "recipients":"1",
      "queue_num":"1",
      "success_num":"1",
      "delivered":1,
      "unique_opened":1,
      "unique_clicked":0,
      "attempted":1
   },
   ...
]

Campaigns - get instance

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/campaigns/:id HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
    "id": "104633",
    "account_id": "785618",
    "name": "Cmp1080",
    "type": "CAMPAIGN",
    "subject": "Special Offer #2",
    "html_body": "<!DOCTYPE HTML>\n<html>\n<head>\n\n\n\n</head>\n<body>...</body></html>",
    "text_body": "Unsubscribe: [[unsubscribe_link]][[account:business]][[account:address_1]][[account:address_2]][[account:city]][[account:postal_code]][[account:country]]",
    "sender_id": "784",
    "template_id": null,
    "reply_to_id": "784",
    "sent_count_cache": "1",
    "open_count_cache": "0",
    "click_count_cache": "0",
    "ga_enabled": null,
    "ga_campaign_title": null,
    "campaign": {
        "id": "104633",
        "name": "Cmp1080",
        "recipients_count_cache": "1",
        "status": "SENT",
        "scheduled_time": null,
        "send_time": "2016-03-17 16:39:07",
        "timezone": null,
        "confirmation_email_address": "admin@yoursite.com"
    },
    "lists": [
        {
            "list_id": "251398",
            "segment_id": "831",
            "list_name": "Test List Zero",
            "segment_name": "2222"
        }
    ]
}

Campaigns - create instance

Request endpoint:

POST https://app.emailchef.com/apps/api/v1/campaigns HTTP/1.1

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Request body:

{
    "instance_in": {
        "name":"My Campaign",                                      
        "type":"CAMPAIGN",                                                                  
        "subject":"Special Offer #2",                                                             
        "html_body":"<html><head></head><body></body></html>", 
        "text_body":"Text version",                                                                     
        "sender_id":"<sender_id>",                                                                  
        "reply_to_id":"<reply_sender_id>",                                                                
        "confirmation_email_address":"yourconfirmationaddress@mysite.com",                           
        "lists":[                                                                           
            {"list_id":"<list_id>"},
            {"list_id":"<list_id>", "segment_id":"<segment_id>"},
            ...
        ]
    }
}

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
    "status": "OK",
    "id": "104636"
}

Campaigns - update instance

Request endpoint:

PUT https://app.emailchef.com/apps/api/v1/campaigns/:id HTTP/1.1

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Request body:

{
    "instance_in": {
        "name":"My Campaign",                                      
        "type":"CAMPAIGN",                                                                  
        "subject":"Special Offer #2",                                                             
        "html_body":"<html><head></head><body></body></html>", 
        "text_body":"Text version",                                                                     
        "sender_id":"<sender_id>",                                                                  
        "reply_to_id":"<reply_sender_id>",                                                                
        "confirmation_email_address":"yourconfirmationaddress@mysite.com",                           
        "lists":[                                                                           
            {"list_id":"<list_id>"},
            {"list_id":"<list_id>", "segment_id":"<segment_id>"},
            ...
        ]
    }
}

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
    "status": "OK",
    "id": "104636"
}

Campaigns - delete instance

Request endpoint:

DELETE https://app.emailchef.com/apps/api/v1/campaigns/:id HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
    "status": "OK",
    "id": "104636"
}

Campaigns - send test email

Request endpoint:

PUT https://app.emailchef.com/apps/api/v1/campaigns/:id/sendtest HTTP/1.1

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Request body:

{
  "instance_in": {
    "email": "fzancan+111@gmail.com"
  }
}

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
    "status": "OK",
}

Campaigns - send campaign

Request endpoint:

PUT https://app.emailchef.com/apps/api/v1/campaigns/:id/send HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
    "status": "OK",
}

Campaigns - schedule

Request endpoint:

PUT https://app.emailchef.com/apps/api/v1/campaigns/:id/schedule HTTP/1.1

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Request body:

{
    "instance_in": {
        "timezone": 5,
        "scheduled_time": "2017-01-01 00:00:00"
    }
}

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
    "status": "OK",
}

Campaigns - cancel scheduling

Request endpoint:

PUT https://app.emailchef.com/apps/api/v1/campaigns/:id/unschedule HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
    "status": "OK",
    "campaign_id": "4637"
}

Campaigns - archive

Request endpoint:

PUT https://app.emailchef.com/apps/api/v1/campaigns/:id/archive HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
    "status": "OK",
    "campaign_id": "4657"
}

Campaigns - unarchive

Request endpoint:

PUT https://app.emailchef.com/apps/api/v1/campaigns/:campaign_id/archivecampaign HTTP/1.1

campaign_id parameter is the id of the campaign to archive

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
    "status": "OK",
    "campaign_id": "4657"
}

Campaigns - clone

Request endpoint:

POST https://app.emailchef.com/apps/api/v1/newsletters?clone=1 HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Request body:

{
  "instance_in": {
    "id": "<campaign id>"
  }
}

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
    "status": "OK",
    "id": "<new campaign id>"
}

Campaigns - get links collection

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/campaigns/:id/links HTTP/1.1

Request headers:

authkey: <your_authentication_key>

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

[
  {
    "url": "http://www.omicronmedia.com",
    "name": "untitled_link_1",
    "id": "9620"
  },
  {
    "url": "https://twitter.com/SendBlaster",
    "name": "untitled_link_12",
    "id": "9631"
  },
  {
    "url": "https://plus.google.com/u/0/b/101921168419294185408/101921168419294185408/po",
    "name": "untitled_link_13",
    "id": "9632"
  },
  ...
]

Send Mail

Request endpoint:

POST https://app.emailchef.com/apps/api/v1/sendmail HTTP/1.1

This resource allows the user to send an email to an arbitrary contact, through eMailChef’s SMTP server.

Actually, and if not differently agreed upon, there’s a limit of 1000 emails sent per day.

Emails sent through this interface are also listed into the profile’s “My Activities” panel.

The reply_to request member is optional.

Request headers:

authkey: <your_authentication_key>

Request body:

{
  "instance_in": {
    "sender_id": nnnn,
    "to": {
      "email": "recipient@hisdomain.com",
      "name": "John Smith"
    },
    "subject": "Subject here",
    "text_body": "Plain text body here",
    "html_body": "Full HTML body here",
    "reply_to": "reply-to-address@otherdomain.com"
  }
}

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json

Response body:

{
    "status": "OK"
}

Error Response body:

{
    "status": "ERROR",
    "message": "sender_not_verified"
}

{
    "status": "ERROR",
    "message": "sender_not_found"
}

{
    "status": "ERROR",
    "message": "send_limit_exceeded"
}

SMS - send

Request endpoint:

POST https://app.emailchef.com/apps/api/v1/sms/send HTTP/1.1

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Alternative Request headers:

username: <your_emailchef_username>
password: <your_emailchef_password>
Content-Type: application/json; charset=utf-8

Request body:

{
   "instance_in":{
        "from": "39000", 
        "to" : "39001;39002",
        "bulk_id": "bulk_campaign_name",
        "text": "sms text",
        "notify_url": "url for message statuses notification" 
  }
}

This is the complete parameters list:

parameter	description
from (optional)	If empty, default number was sent.
to *	each number should have max 16 chars You can enter up to 100 numbers (in international format) separated by semi-colon (“;”).
text (optional)	message text (160 chars for single message, max. 640 chars). If empty, an empty message will be sent.
bulk_id (optional)	you can provide an univoque ID for checking message statuses later.
notify_url (optional)	notification URL to receive message statuses

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

Response body:

{
    "status": "success",
    "bulk_id": "bulk_campaign_name",
    "balance": {
        "balance": 1.18,
        "currency": "EUR"
    },
    "statuses": [
        {
            "to": "39001",
            "message_id": "12345678",
            "sms_count": 1,
            "status": "PENDING_ENROUTE"
        },
        {
            "to": "39002",
            "message_id": "12345678",
            "sms_count": 1,
            "status": "PENDING_ENROUTE"
        }
    ]
}

The indicated balance is the one available before sending.

SMS - get balance

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/sms/balance HTTP/1.1

GET sms balance

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Alternative Request headers:

username: <your_emailchef_username>
password: <your_emailchef_password>
Content-Type: application/json; charset=utf-8

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

Response body:

{
    "balance": 1.06,
    "currency": "EUR"
}

SMS - get status message

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/sms/status/:messageId HTTP/1.1

GET sms message status

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Alternative Request headers:

username: <your_emailchef_username>
password: <your_emailchef_password>
Content-Type: application/json; charset=utf-8

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

Response body:

[
    {
        "bulk_id": null,
        "message_id": "123456",
        "to": "39002",
        "from": "39001",
        "text": "test message",
        "sent_at": "2020-11-23T13:37:15.000+00:00",
        "done_at": "2020-11-23T13:37:15.000+00:00",
        "sms_count": 1,
        "price": {
            "price": 0.06,
            "currency": "EUR"
        },
        "status": "DELIVERED_TO_HANDSET",
        "error": "NO_ERROR"
    }
]

SMS - get bulk message statuses

Request endpoint:

GET https://app.emailchef.com/apps/api/v1/sms/bulk/status/:bulkId HTTP/1.1

GET bulk message statuses

Request headers:

authkey: <your_authentication_key>
Content-Type: application/json; charset=utf-8

Alternative Request headers:

username: <your_emailchef_username>
password: <your_emailchef_password>
Content-Type: application/json; charset=utf-8

Response headers:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

Response body:

[
    {
        "bulk_id": "bulk id provided",
        "message_id": "123456",
        "to": "39002",
        "from": "39001",
        "text": "test message",
        "sent_at": "2020-11-23T13:37:15.000+00:00",
        "done_at": "2020-11-23T13:37:15.000+00:00",
        "sms_count": 1,
        "price": {
            "price": 0.06,
            "currency": "EUR"
        },
        "status": "DELIVERED_TO_HANDSET",
        "error": "NO_ERROR"
    }
]

Errors

The eMailChef API uses the following error codes:

Error Code	Meaning
400	Bad Request – Your request sucks
401	Unauthorized – Your API key is wrong
403	Forbidden – The resource requested is hidden for administrators only
404	Not Found – The specified resource could not be found, or it is not accessible for your authorization level
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.

eMailChef Public API

Version 1.3 2023-02-24

Getting started

Data interchange format

Accessing resources

Error scenarios while accessing resources

Authentication (a.k.a. login)

Request endpoint:

Meta Resources

Application

Request endpoint:

Appconfig

I18N

Request endpoint:

Language names

Request endpoint:

Policies

Request endpoint:

Preferences

Request endpoint:

Segments

Request endpoint:

Userlog - get collection

Request endpoint:

Userlog - get count

Request endpoint:

Plans - get collection

Request endpoint:

Plans - get instance

Request endpoint:

Packages - get collection

Request endpoint:

Packages - get instance

Request endpoint:

Senders - get collection

Request endpoint:

Timezones - get collection

Request endpoint:

Resources

Account

Request endpoint:

Account infos - get instance

Request endpoint:

Account infos - update instance

Request endpoint:

Subscription

Request endpoint:

Lists - get collection

Request endpoint:

Lists - get instance

Request endpoint:

Lists - get stats

Request endpoint:

Lists - unsubscribe

Request endpoint:

Lists - create instance

Request endpoint:

Lists - update instance

Request endpoint:

Lists - delete instance

Request endpoint:

Contacts - get count

Request endpoint:

Contacts - get collection

Request endpoint:

Contacts - get instance

Request endpoint:

Contacts - create instance

Request endpoint:

Contacts - update instance

Request endpoint:

Predefined Fields - get collection

Request endpoint:

Custom Fields - get collection

Request endpoint:

Custom Fields - get instance

Request endpoint:

Custom Fields - get count

Request endpoint:

Custom Fields - create instance