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.
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.
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.
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.
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.
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.
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.
Base URL https://usemjml.com. Everything answers JSON, including errors —
except /api/render, which answers the HTML itself unless you ask for JSON.
/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.
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}}'
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
{
"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.
/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.
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
{
"valid": false,
"errors": [
{
"line": 1,
"message": "mj-text cannot be used inside mj-body",
"tagName": "mj-text"
}
],
"validationLevel": "strict",
"mjml": "5.4.1"
}
/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.
curl -X POST https://usemjml.com/api/me \
-H 'X-API-Key: mjml_your_key'
{
"valid": true,
"email": "you@example.com"
}
/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.
curl https://usemjml.com/api/health
{
"status": "ok",
"renderer": "up",
"mjml": "5.4.1",
"message": null
}
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. |
| Code | When |
|---|---|
200 | Rendered or validated. |
401 | A key was sent, but it is unknown or not activated yet — or /api/me was called without one. |
413 | The template is larger than 2 MiB. |
415 | A Content-Type this API does not read MJML from. |
422 | Empty body, unknown option, or a template that fails strict validation. |
429 | A rate limit is exhausted — see Retry-After. |
502 | The renderer did not answer. Retry. |
503 | /api/health only: the renderer is down. |
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.
X-API-Key: mjml_your_key
Authorization: ApiKey mjml_your_key
Authorization: Bearer mjml_your_key
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.
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.
{
"statusCode": 429,
"error": "Too Many Requests",
"message": "This API key is at its rate limit."
}
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.
They are rendered and dropped. Nothing is stored, nothing is logged beyond the fact that a request happened.
Yes. The renderer behind this API is the open-source
usemjml
server — the same image, one docker run away.
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.
2 MiB, which is far more than an email ever needs. Anything larger comes back as
413.