Skip to content
MJML · HTTP API

Render MJML
without a build step.

One POST, responsive email HTML back. No Node toolchain in your project, no MJML upgrade in your deploy pipeline — just an endpoint your app, your CI or your CMS can call.

Render a template
curl -X POST https://usemjml.com/api/render \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: mjml_your_key' \
  -d '{"mjml": "<mjml><mj-body><mj-section><mj-column><mj-text>Hello</mj-text></mj-column></mj-section></mj-body></mjml>"}'

Free tier without registration: 100 calls per hour, shared by all anonymous callers. With a key: 150 per hour, all yours.

Four endpoints, that is the whole API

Send a template, get HTML. Ask whether a template is sound before you send it. Ask whether your key works, and whether the service is up. Everything else is an option on one of those calls.

1

Register

Drop your email address in the form below. You get a key by mail and activate it with one click. No account, no password, no invoice.

2

Send your MJML

POST /api/render with the template in a JSON envelope, or as a raw body straight from your file. Options travel in the body or as query parameters.

3

Ship the HTML

The answer is the email HTML, inlined and table-based, ready for your mailer. Ask for JSON instead and you get the validation errors alongside it.

Endpoints

Base URL https://usemjml.com. Everything answers JSON, including errors — except /api/render, which answers the HTML itself unless you ask for JSON.

POST /api/render API key optional

Renders MJML to email HTML. Answers text/html by default; add Accept: application/json or ?format=json to get the HTML plus the validation errors MJML reported on the way.

JSON envelope
curl -X POST https://usemjml.com/api/render \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: mjml_your_key' \
  -d '{"mjml": "<mjml>…</mjml>", "config": {"minify": true}}'
Raw file, options as query parameters
curl -X POST 'https://usemjml.com/api/render?minify=true' \
  -H 'Content-Type: text/plain' \
  -H 'X-API-Key: mjml_your_key' \
  --data-binary @mail.mjml
Response with ?format=json
{
  "html": "<!doctype html>…",
  "errors": [],
  "mjml": "5.4.1"
}

The HTML response carries X-MJML-Errors with the number of soft validation errors and X-MJML-Version with the MJML version that rendered it.

POST /api/validate API key optional

Checks a template and throws the HTML away. Always answers 200, also for a broken template: "invalid, and here is where" is an answer, not a failed request. Use it in a linter, a pre-commit hook or a CMS field validator.

Validate a file
curl -X POST 'https://usemjml.com/api/validate?validationLevel=strict' \
  -H 'Content-Type: text/plain' \
  -H 'X-API-Key: mjml_your_key' \
  --data-binary @mail.mjml
Response
{
  "valid": false,
  "errors": [
    {
      "line": 1,
      "message": "mj-text cannot be used inside mj-body",
      "tagName": "mj-text"
    }
  ],
  "validationLevel": "strict",
  "mjml": "5.4.1"
}
POST /api/me API key required, no rate limit

Checks the key you send. 200 with the email address the key was registered for when it is valid, 401 when it is missing, unknown or not activated yet. Handy as a smoke test right after you configured the key somewhere — it costs nothing from your limit.

Check your key
curl -X POST https://usemjml.com/api/me \
  -H 'X-API-Key: mjml_your_key'
Response
{
  "valid": true,
  "email": "you@example.com"
}
GET /api/health No key, no rate limit

Liveness of the API and of the renderer behind it. 200 while rendering works, 503 when it does not — so a monitor can watch it without a key, and without ever being locked out by a limit.

Probe
curl https://usemjml.com/api/health
Response
{
  "status": "ok",
  "renderer": "up",
  "mjml": "5.4.1",
  "message": null
}

Options

Options go into config in the JSON body, or straight onto the URL as query parameters — handy when the body is a raw template. Anything not listed here is rejected with 422, on purpose: filePath, includePath and mjmlConfigPath would point the renderer at a file system, and that stays ours.

Option Values Default What it does
validationLevel skip, soft, strict soft soft renders and reports, strict refuses to render an invalid template (422), skip only catches what cannot be parsed at all.
minify true, false false Minify the generated HTML.
beautify true, false false Pretty-print the generated HTML.
keepComments true, false true Keep HTML comments in the output.
fonts object of name → https:// URL MJML defaults Web fonts the template may reference.

Status codes

Code When
200Rendered or validated.
401A key was sent, but it is unknown or not activated yet — or /api/me was called without one.
413The template is larger than 2 MiB.
415A Content-Type this API does not read MJML from.
422Empty body, unknown option, or a template that fails strict validation.
429A rate limit is exhausted — see Retry-After.
502The renderer did not answer. Retry.
503/api/health only: the renderer is down.

Authentication

The key is optional. Without one you are a guest on the anonymous limit everybody shares; with one you get your own budget, counted per key rather than per machine — so your CI, your staging box and your laptop share the same allowance.

Three spellings, all accepted
X-API-Key: mjml_your_key
Authorization: ApiKey mjml_your_key
Authorization: Bearer mjml_your_key
  • A key belongs to one email address, and one address has one key.
  • It works the moment you follow the activation link in the mail.
  • Registering again sends you the same key, never a second one.
  • Send it over HTTPS and keep it out of your repository — it is a bearer credential.

Rate limits

Calls without a key draw from one budget shared by every anonymous caller; calls with a key draw from that key's own. Rendering is CPU-bound — one template blocks a core while it renders — so the free tier is capped as a whole rather than per machine.

Limit Counted per Budget Window
Anonymous the whole service 100 requests sliding hour
With API key API key 150 requests sliding hour
Enterprise API key Get in touch sliding hour

Every answer carries what is left of the limit it counted against — the key's, or the shared anonymous one.

Response headers
X-RateLimit-Limit: 150
X-RateLimit-Remaining: 148
X-RateLimit-Reset: 1758106800

Over the limit you get 429 with a Retry-After in seconds, and a body that says which limit stopped you.

429 response
{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "This API key is at its rate limit."
}

Get your API key

Enter your email address and we send you a key plus an activation link. The key works as soon as you follow that link. We keep the address to tie the key to it — nothing else.

Lost your key? Enter the same address again and we send it back to you.

Good to know

What happens to my templates?

They are rendered and dropped. Nothing is stored, nothing is logged beyond the fact that a request happened.

Can I run this myself?

Yes. The renderer behind this API is the open-source usemjml server — the same image, one docker run away.

Is mj-include supported?

No. File includes would mean reading from a file system on your behalf, so they stay off. Assemble partials on your side and send one template.

How big may a template be?

2 MiB, which is far more than an email ever needs. Anything larger comes back as 413.