{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/mandrill/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Switch from Mandrill: Getting started","siteUrl":"https://dev.mailjet.com/","projectTitle":"Mailjet Developer Documentation","description":"Start your Mandrill-to-Mailjet migration here. Covers API terminology mapping, RESTful conventions, HTTP Basic Auth, and status codes for the Mailjet Send API.","image":"https://dev.mailjet.com/og-image.png","lang":"en-US","keywords":["Mailjet API","Email API","Content API","SMTP Relay","transactional email","email delivery","Send API","email templates","developer documentation"],"meta":[{"name":"og:type","content":"website"},{"name":"og:site_name","content":"Mailjet Developer Documentation"},{"name":"twitter:card","content":"summary_large_image"},{"name":"robots","content":"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1"},{"name":"googlebot","content":"index, follow, max-snippet:-1, max-image-preview:large"}],"jsonLd":{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://dev.mailjet.com/#organization","name":"Mailjet","alternateName":"Sinch Mailjet","url":"https://www.mailjet.com","logo":"https://assets.mailjet.com/lib/images/mailjetLogo/mj_logo_with_text_color.png","parentOrganization":{"@type":"Organization","name":"Sinch","url":"https://www.sinch.com"}},{"@type":"WebSite","@id":"https://dev.mailjet.com/#website","name":"Mailjet Developer Documentation","description":"Official developer documentation for the Mailjet Email API, Content API and SMTP Relay.","url":"https://dev.mailjet.com/","inLanguage":"en-US","publisher":{"@id":"https://dev.mailjet.com/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://dev.mailjet.com/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]},"llmstxt":{"hide":false,"title":"Mailjet Developer Documentation","description":"Developer documentation for the Mailjet Email API, Content API and SMTP Relay - guides, API references and code samples for sending, templating and tracking email at scale.","details":{"content":"Mailjet (part of Sinch) provides APIs for sending and managing email.\n\nThis documentation covers four main areas:\n\n- **Email API** - the Send API (v3 and v3.1) for transactional and marketing email,\n  plus contact management, segmentation, campaigns, statistics, webhooks, the Parse API\n  and the Mailjet Templating Language.\n- **Content API** - programmatic management of email templates, template contents,\n  images, labels and authentication tokens (v1).\n- **SMTP Relay** - sending through Mailjet's SMTP servers, including custom headers.\n- **API Reference** - the complete, generated reference for every endpoint, built directly\n  from the OpenAPI specifications.\n\nBase URL for all REST APIs: `https://api.mailjet.com`.\nAuthentication uses HTTP Basic auth with an API key and secret key.\n\n## Machine-readable entry points\n\nPrefer these when you need the API surface in as few requests as possible:\n\n- `/openapi/openapi-mailjet.md` - the **complete** Email API reference (every endpoint,\n  grouped by resource) as a single Markdown document.\n- `/openapi/openapi-passport.md` - the **complete** Content API reference as a single\n  Markdown document.\n- `/_bundle/openapi/openapi-mailjet.yaml` - the raw, fully bundled OpenAPI 3 description\n  of the Email API.\n- `/_bundle/openapi/openapi-passport.yaml` - the raw, fully bundled OpenAPI 3 description\n  of the Content API.\n- `/sitemap.xml` - every indexable URL on this site.\n\nEvery page on this site is also available as clean Markdown by appending `.md` to its URL."},"sections":[{"title":"Email API","description":"Sending, contacts, campaigns, statistics, webhooks and templating.","includeFiles":["docs/email-api/**/*.md"],"excludeFiles":[]},{"title":"Content API","description":"Manage templates, template contents, images, labels and tokens.","includeFiles":["docs/content-api/**/*.md","docs/content-api.md"],"excludeFiles":[]},{"title":"SMTP Relay","description":"Send email through Mailjet's SMTP servers.","includeFiles":["docs/smtp-relay/**/*.md"],"excludeFiles":[]},{"title":"API Reference","description":"Complete generated reference for every Mailjet API endpoint.","includeFiles":["openapi/openapi-mailjet.yaml","openapi/openapi-passport.yaml","docs/api-reference/**/*.md"],"excludeFiles":[]},{"title":"Migrating from Mandrill","description":"Guides for switching from Mandrill to Mailjet.","includeFiles":["docs/mandrill/**/*.md"],"excludeFiles":[]}],"excludeFiles":[]},"priority":0.3},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"switch-from-mandrill-getting-started","__idx":0},"children":["Switch from Mandrill: Getting started"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Welcome to this API reference. It has been designed to help you transition your API integration from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://mandrill.com"},"children":["Mandrill/Mailchimp"]}," to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://mailjet.com"},"children":["Mailjet"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Mandrill says"},"children":["Mandrill says"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Mailjet says"},"children":["Mailjet says"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Comments"},"children":["Comments"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["merge vars"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["contact metadata or variables"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Mailjet being an all-in-one solution, we accept both contact based properties and message variables"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Messages"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Send API"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Templates"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Template"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Mailjet API resource names are always singular"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Senders"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Sender"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Mailjet API resource's names are always singular"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Webhook"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Event API"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Inbound"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Parse API"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tags"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Custom ID"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"about-the-mailjet-restful-api","__idx":1},"children":["About the Mailjet RESTful API"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"api-in-a-nutshell","__idx":2},"children":["API in a Nutshell"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The Mailjet API is designed to be ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"http://en.wikipedia.org/wiki/Representational_state_transfer"},"children":["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 (",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"http://en.wikipedia.org/wiki/CRUD"},"children":["CRUD"]},") resources. Also, each resource has a URI (Unique Resource Identifier) to help access its properties."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The CRUD methods on the Mailjet API correspond to HTTP verbs ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]},", so that, depending on the resources and providing you have the access rights, you can do the following :"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /$resource"]}," gives you a list of resources of type $resource"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /$resource/$id"]}," gives you a single resource of type $resource, identified by the id $id, using its URI"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /$resource"]}," allows you to create a resource of type $resource"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT /$resource/$id"]}," allows you to update an existing resource of type $resource, identified by the id $id, using its URI"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /$resource/$id"]}," allows you to delete a single resource of type $resource, identified by the id $id, using its URI"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each resource has a list of properties and methods. You can see them in our ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/api-reference/"},"children":["API reference"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On the Mailjet API, all ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]}," method use will behave like a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["###Authenticate"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In order to use the Mailjet API you have to authenticate using ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"http://en.wikipedia.org/wiki/Basic_access_authentication"},"children":["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."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["TIP: You can find the API Key and the API Private Key in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://app.mailjet.com/account/api_keys"},"children":["API keys Management"]}," section."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"#To make better use of our cURL examples you can set your keys in your environment variables with the following commands:\nexport MJ_APIKEY_PUBLIC=xxxxxxxxxxxxxxxxxxxxxx\nexport MJ_APIKEY_PRIVATE=xxxxxxxxxxxxxxxxxxxxxxx\n\n#View user information : now, you don't need to replace $MJ_APIKEY_PUBLIC and $MJ_APIKEY_PRIVATE when running a cURL command\ncurl --user \"$MJ_APIKEY_PUBLIC:$MJ_APIKEY_PRIVATE\" https://api.mailjet.com/v3/REST/user\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The server should respond with the following data:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"Count\": 1,\n  \"Data\": [\n    {\n      \"ACL\": \"\",\n      \"CreatedAt\": \"\",\n      \"Email\": \"miss@mailjet.com\",\n      \"ID\": \"\",\n      \"LastIp\": \"\",\n      \"LastLoginAt\": \"\",\n      \"Locale\": \"\",\n      \"MaxAllowedAPIKeys\": \"5\",\n      \"Timezone\": \"\",\n      \"Username\": \"\",\n      \"WarnedRatelimitAt\": \"\"\n    }\n  ],\n  \"Total\": 1\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In this example :"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$MJ_APIKEY_PUBLIC"]}," is your API Key"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["$MJ_APIKEY_PRIVATE"]}," is your API Private Key"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Both these keys can be found in your control panel, once you're logged-in and your account is provisioned (activated)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The usual json payload response will have the following structure : ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{\"Count\": int, \"Data\": array, \"Total\": int}"]}," where ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Count"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Total"]}," represent the number of lines affected by your API call. When using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["countOnly"]}," filter ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Total"]}," will be the global number of elements corresponding to your API call."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["###Status Codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These status codes will be sent back by the API to notify of the success or failure of your calls."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["200"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OK"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["All went well. Congrats!"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["201"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Created"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," request was successfully executed."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["204"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No Content"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["No content found or expected to return. Returned when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}," was successful."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["304"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not Modified"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]}," request didn't affect any record."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bad Request"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One or more parameters are missing or maybe mispelled (unknown resource or action)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unauthorized"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://app.mailjet.com/account/api_keys"},"children":["API keys Management"]}," section to check your keys."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Forbidden"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["You are not authorised to access this resource."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["404"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Not Found"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The resource with the specified ID you are trying to reach does not exist."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["405"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Method Not Allowed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The method requested on the resource does not exist."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Internal Server Error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ouch! Something went wrong on our side and we apologize! Please contact ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://www.mailjet.com/support"},"children":["our support team"]},", who'll be able to help you on this"]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n    \"ErrorInfo\": \"Bad Request\",\n    \"ErrorMessage\": \"Unknown resource: \\\"contacts\\\"\",\n    \"StatusCode\": 400\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In addition to the status codes, in case of error, you can find hints in a standardized JSON response with the reason under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ErrorMessage"]},"."]}]},"headings":[{"value":"Switch from Mandrill: Getting started","id":"switch-from-mandrill-getting-started","depth":1},{"value":"About the Mailjet RESTful API","id":"about-the-mailjet-restful-api","depth":2},{"value":"API in a Nutshell","id":"api-in-a-nutshell","depth":3}],"frontmatter":{"title":"Getting started","seo":{"description":"Start your Mandrill-to-Mailjet migration here. Covers API terminology mapping, RESTful conventions, HTTP Basic Auth, and status codes for the Mailjet Send API.","priority":0.3,"title":"Switch from Mandrill: Getting started"}},"lastModified":"2026-08-26T10:53:57.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/mandrill/getting-started","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}