# Switch from Mandrill: Getting started

Welcome to this API reference. It has been designed to help you transition your API integration from [Mandrill/Mailchimp](https://mandrill.com) to [Mailjet](https://mailjet.com).

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.

| Mandrill says | Mailjet says | Comments |
|  --- | --- | --- |
| merge vars | contact metadata or variables | Mailjet being an all-in-one solution, we accept both contact based properties and message variables |
| Messages | Send API |  |
| Templates | Template | Mailjet API resource names are always singular |
| Senders | Sender | Mailjet API resource's names are always singular |
| Webhook | Event API |  |
| Inbound | Parse API |  |
| Tags | Custom ID |  |


## About the Mailjet RESTful API

### API in a Nutshell

The Mailjet API is designed to be [RESTful compliant](http://en.wikipedia.org/wiki/Representational_state_transfer). 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](http://en.wikipedia.org/wiki/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](/docs/api-reference/).

Info
On the Mailjet API, all `PUT` method use will behave like a `PATCH` method. The update will affect only the specified properties, the other properties of an existing single resource will not be modified nor deleted. It also means that all non mandatory properties can be omitted from your payload.

###Authenticate

In order to use the Mailjet API you have to authenticate using [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication). 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.

Info
TIP: You can find the API Key and the API Private Key in the [API keys Management](https://app.mailjet.com/account/api_keys) section.

```bash
#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:

```json
{
  "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.

| Code |  | Description |
|  --- | --- | --- |
| 200 | OK | All went well. Congrats! |
| 201 | Created | The `POST` request was successfully executed. |
| 204 | No Content | No content found or expected to return. Returned when `DELETE` was successful. |
| 304 | Not Modified | The `PUT` request didn't affect any record. |
| 400 | Bad Request | One or more parameters are missing or maybe mispelled (unknown resource or action) |
| 401 | Unauthorized | You have specified an incorrect Api Key / API Secret Key. You may be unauthorized to access the API or your API key may be expired. Visit [API keys Management](https://app.mailjet.com/account/api_keys) section to check your keys. |
| 403 | Forbidden | You are not authorised to access this resource. |
| 404 | Not Found | The resource with the specified ID you are trying to reach does not exist. |
| 405 | Method Not Allowed | The method requested on the resource does not exist. |
| 500 | Internal Server Error | Ouch! Something went wrong on our side and we apologize! Please contact [our support team](https://www.mailjet.com/support), who'll be able to help you on this |


```json
{
    "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`.