Switch from Mandrill: Getting started

Welcome to this API reference. It has been designed to help you transition your API integration from Mandrill/Mailchimp to Mailjet.

Mailjet was built as an all-in-one solution from day one, being convinced that marketing and transactional email must closely feed into each other.

To ease the migration process, this documentation will follow the same layout as the Mandrill one, so you can easily find your way around our API and understands faster how to remap with your own integration.

The Mailjet API is designed to be RESTful compliant. This means that the API communicates over HTTP (including the use of HTTP verbs) . The API allows you to create, read, update and delete (CRUD) resources. Also, each resource has a URI (Unique Resource Identifier) to help access its properties.

The CRUD methods on the Mailjet API correspond to HTTP verbs POST, GET, PUT and DELETE, so that, depending on the resources and providing you have the access rights, you can do the following :

• GET /$resource gives you a list of resources of type $resource
• GET /$resource/$id gives you a single resource of type $resource, identified by the id $id, using its URI
• POST /$resource allows you to create a resource of type $resource
• PUT /$resource/$id allows you to update an existing resource of type $resource, identified by the id $id, using its URI
• DELETE /$resource/$id allows you to delete a single resource of type $resource, identified by the id $id, using its URI

Each resource has a list of properties and methods. You can see them in our API reference.

###Authenticate

In order to use the Mailjet API you have to authenticate using HTTP Basic Auth. HTTP Basic Auth requires you to provide a username and a password for each API request. The username is your API Key and the password is your API Secret Key, which are both generated for you after registration.

#To make better use of our cURL examples you can set your keys in your environment variables with the following commands:
export MJ_APIKEY_PUBLIC=xxxxxxxxxxxxxxxxxxxxxx
export MJ_APIKEY_PRIVATE=xxxxxxxxxxxxxxxxxxxxxxx

#View user information : now, you don't need to replace $MJ_APIKEY_PUBLIC and $MJ_APIKEY_PRIVATE when running a cURL command
curl --user "$MJ_APIKEY_PUBLIC:$MJ_APIKEY_PRIVATE" https://api.mailjet.com/v3/REST/user

The server should respond with the following data:

{
  "Count": 1,
  "Data": [
    {
      "ACL": "",
      "CreatedAt": "",
      "Email": "miss@mailjet.com",
      "ID": "",
      "LastIp": "",
      "LastLoginAt": "",
      "Locale": "",
      "MaxAllowedAPIKeys": "5",
      "Timezone": "",
      "Username": "",
      "WarnedRatelimitAt": ""
    }
  ],
  "Total": 1
}

Most developers use one of our API libraries for their production systems and the respective library documentation tells you where to place your API Keys. However for testing purposes it can be nice to query the API directly from the shell.

In this example :

• $MJ_APIKEY_PUBLIC is your API Key
• $MJ_APIKEY_PRIVATE is your API Private Key

Both these keys can be found in your control panel, once you're logged-in and your account is provisioned (activated).

The usual json payload response will have the following structure : {"Count": int, "Data": array, "Total": int} where Count and Total represent the number of lines affected by your API call. When using the countOnly filter Total will be the global number of elements corresponding to your API call.

###Status Codes

These status codes will be sent back by the API to notify of the success or failure of your calls.

{
    "ErrorInfo": "Bad Request",
    "ErrorMessage": "Unknown resource: \"contacts\"",
    "StatusCode": 400
}

In addition to the status codes, in case of error, you can find hints in a standardized JSON response with the reason under ErrorMessage.