{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/content-api/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Getting Started with Content API Templates","siteUrl":"https://dev.mailjet.com/","projectTitle":"Mailjet Developer Documentation","description":"Start building email templates with the Mailjet Content API. Covers two-step create-and-add-content flow, four template purposes, and edit modes (HTML, MJML).","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":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"getting-started","__idx":0},"children":["Getting Started"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"creating-an-email-template","__idx":1},"children":["Creating an email template"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Creating an email template via the Content API is a two-step process:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create the Template: This step involves creating the basic structure of the template, including its name, description and purpose."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add Content to the Template: Once the template is ready, the next step is to add content to the template. This content could include text, images, and variables needed for personalizing the email."]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"template-purpose","__idx":2},"children":["Template Purpose"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you would like your template to be visible in the Mailjet user interface, you will need to assign a purpose to your template."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Mailjet has four types of templates:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"b","attributes":{},"children":["Marketing"]},": Templates used for promotional content, such as newsletters, sales announcements, and special offers. These are sent using Campaigns."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"b","attributes":{},"children":["Transactional"]},": Templates for operational emails, like order confirmations, shipping notifications, and password resets. These are sent via API or SMTP."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"b","attributes":{},"children":["Automation"]},": Templates designed for automated email workflows, such as welcome emails, birthday messages, and follow-ups. These are sent within an automation workflow."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"b","attributes":{},"children":["Opt-in"]},": Templates for double opt-in emails for your Mailjet forms. These are sent automatically when a contact fills out your form."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each category corresponds to a purpose in the Content API:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["marketing"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactional"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["automation"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["opt-in"]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Assigning a purpose is optional. However, if you do not assign a purpose to your template, ",{"$$mdtype":"Tag","name":"b","attributes":{},"children":["the template will not be available in the UI"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"template-purpose-and-token-permissions","__idx":3},"children":["Template Purpose and Token Permissions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is also important to assign a template purpose to ensure proper access control as token permissions are aligned with the purposes of the templates."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For example, if a template has a purpose of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactional"]},", the user must have a token with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactional"]}," permissions to access it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"edit-mode","__idx":4},"children":["Edit Mode"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are four edit modes in Mailjet:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}," = Drag-and-drop builder (cannot be created via API)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2"]}," = HTML builder"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["3"]}," = Saved Section builder (cannot be created via API)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4"]}," = MJML builder"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"b","attributes":{},"children":["Default Value"]}," ","The default edit mode is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2"]}," (HTML builder)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"api-usage","__idx":5},"children":["API Usage"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Edit Mode ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["2"]}," (HTML builder) and Edit Mode ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4"]}," (MJML builder) can be used to create and edit templates via API."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When using Edit Mode ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4"]},", the template must be coded in MJML and published in the user interface before it can be sent."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"other-edit-modes","__idx":6},"children":["Other Edit Modes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Edit Mode ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}," (Drag-and-drop builder) and Edit Mode ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["3"]}," (Saved Section builder) will be visible when retrieving a list of templates using this endpoint: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET https://api.mailjet.com/v1/REST/templates"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["As long as the content of the template has been been published, you can use a template created in Edit Mode ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["1"]}," (Drag-and-drop builder) to send via API."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can always publish the content of a template at this endpoint: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST https://api.mailjet.com/v1/REST/templates/:id/contents/publish"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Warning!"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Creating or editing templates in Edit Mode 1 or Edit Mode 3 is at your own risk. These templates may break in the UI, and Mailjet will not be able to repair them. Please ensure you follow these guidelines to avoid any issues with your templates."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"locale","__idx":7},"children":["Locale"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When creating template content, a locale is required in order to be able to save and send your template."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"list-of-accepted-locales","__idx":8},"children":["List of Accepted Locales"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["en_US"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fr_FR"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["da_DK"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["de_DE"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["es_ES"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nl_NL"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["it_IT"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sv_SE"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pt_BR"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pt_PT"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ru_RU"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ja_JP"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["lv_LV"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["is_IS"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ro_RO"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["el_GR"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ar_AR"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["sk_SK"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cs_CZ"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pl_PL"]}," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["zh_CN"]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Important Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the purpose of your template is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["automation"]},", only the following locales are accepted:"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["en_US"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["fr_fr"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["de_DE"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ìt_IT"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["es_ES"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"content-type","__idx":9},"children":["Content Type"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Template content is categorized by content types. There are three types:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["D = Draft"]},": Template content is always created with this status."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["P = Published"]},": Content that has been published will have this status."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["A = Autosave"]},": Indicates that an autosave has occurred in the user interface."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By default, the content type is set to D."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You cannot directly ,",{"$$mdtype":"Tag","name":"b","attributes":{},"children":["modify"]}," the content type field via API, but you can ",{"$$mdtype":"Tag","name":"b","attributes":{},"children":["search"]}," by content type."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To send your template, it must have a content type of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["P"]},", meaning it has been published. To publish your template, use its ID with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," request to this endpoint: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["https://api.mailjet.com/v1/REST/templates/:id/contents/publish"]},"."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Since the Content API always publishes the latest draft, you may want to search by content type D before publishing to ensure you are publishing the correct content."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Additionally, Mailjet stores up to 5 versions of content per content type for a single template. If you need to revert to a previous version, you can also search by content type. For details on reverting to a previous version of template content, refer to our FAQ."]}]},"headings":[{"value":"Getting Started","id":"getting-started","depth":1},{"value":"Creating an email template","id":"creating-an-email-template","depth":2},{"value":"Template Purpose","id":"template-purpose","depth":2},{"value":"Template Purpose and Token Permissions","id":"template-purpose-and-token-permissions","depth":3},{"value":"Edit Mode","id":"edit-mode","depth":2},{"value":"API Usage","id":"api-usage","depth":3},{"value":"Other Edit Modes","id":"other-edit-modes","depth":3},{"value":"Locale","id":"locale","depth":2},{"value":"List of Accepted Locales","id":"list-of-accepted-locales","depth":3},{"value":"Content Type","id":"content-type","depth":2}],"frontmatter":{"title":"Mailjet Content API","seo":{"title":"Getting Started with Content API Templates","description":"Start building email templates with the Mailjet Content API. Covers two-step create-and-add-content flow, four template purposes, and edit modes (HTML, MJML)."}},"lastModified":"2026-08-26T10:53:57.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/content-api/email-templates/getting-started-email-template","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}