Why do I get 'template already exists' when creating a Mailgun template?

Template names must be unique within their scope (per domain or per account). Posting a name that's already in use returns a 400 'template already exists' error. Either choose a different name, or add a new version to the existing template via the /versions endpoint instead of creating a new template.

Mailgun

mailgun can't create template

Q: Which fields are required to create a Mailgun template via the API?

The name parameter is always required. To create an active, usable template in a single request you must also include template (the content) and, optionally, tag as a version label. Mailgun templates always render with its built-in, customized Handlebars engine — there is no engine-selection parameter; you cannot substitute Mustache, Liquid, etc. Sending only name stores empty metadata with no active version.

Why Mailgun won't create your email template — duplicate names, missing fields, and the 100-template, 40-version, 100KB limits — plus the exact API fixes.

Updated Jul 1, 2026

The short answer

"Mailgun can't create template" means a POST to Mailgun's Templates API was rejected. The usual causes are a duplicate template name, a missing required name field, or hitting a hard limit: 100 templates per domain/account, 40 versions per template, or 100KB per template. Fix it by using a unique name, sending the required parameters, or deleting old templates/versions to free space.

A failed template creation in Mailgun is almost always a 400-class rejection from the Templates API (POST /v3/{domain_name}/templates or the account-level POST /v4/templates), not a transient outage. Mailgun rejects the request when the payload is malformed, the name collides, or the request would exceed a documented quota.

What causes "Mailgun can't create template"?

There are four distinct causes, and they need different fixes:

Duplicate template name. Template names must be unique within the scope (per domain for domain templates, per account for account templates). Re-posting an existing name returns a "template already exists" 400.
Missing required field. The name parameter is the only strictly required field. To create an active template in one call, also send template (the content) — Mailgun then auto-creates the first version and marks it active. You may include tag to label that version, but if you omit it while sending template, Mailgun assigns the default tag initial. Omitting name returns a 400.
Quota exceeded. Per Mailgun's official limits: 100 templates per domain/account and 40 versions per template. Mailgun also enforces a per-template size cap — check Mailgun's Help Center for the current figure. (Note: older guidance citing "10 versions" is outdated — Mailgun now documents 40.)
Wrong regional base URL. EU-region domains must call https://api.eu.mailgun.net; US-region domains use https://api.mailgun.net. Posting a template to the wrong region (or to a domain that isn't verified/owned by your account) fails even when the body is perfect.

How do I fix "Mailgun can't create template"?

Start by reading the JSON error body — Mailgun states the specific reason there.

1. Send a valid create request with a unique name:

curl -s --user "api:YOUR_API_KEY" \
  https://api.mailgun.net/v3/YOUR_DOMAIN/templates \
  -F name='order-receipt-v2' \
  -F template='<html>{{var}}</html>' \
  -F tag='v1'

For an EU domain, swap the host for api.eu.mailgun.net. Supplying template makes the first version active automatically; the tag here is just a label (omit it and Mailgun uses initial).

2. If the name already exists, either pick a new name, or keep the same template and add a version instead of a new template. A newly created version becomes the active version by default:

curl -s --user "api:YOUR_API_KEY" \
  https://api.mailgun.net/v3/YOUR_DOMAIN/templates/order-receipt-v2/versions \
  -F template='<html>{{var}}</html>' \
  -F tag='v2'

If you instead want to re-activate an existing version, update it with a PUT to .../templates/order-receipt-v2/versions/v2 rather than re-creating it.

3. If you've hit a quota, list what exists and prune:

# List templates (check if you're at 100)
curl -s --user "api:YOUR_API_KEY" \
  https://api.mailgun.net/v3/YOUR_DOMAIN/templates

# Delete an unused template to free a slot
curl -s -X DELETE --user "api:YOUR_API_KEY" \
  https://api.mailgun.net/v3/YOUR_DOMAIN/templates/old-template

If you're at the 40-version cap on a single template, delete old versions rather than the template itself. If your template content is large, trim inline CSS/whitespace or move large assets (images) to hosted URLs instead of embedding them.

4. Confirm region and domain ownership. Verify the domain is added and verified in your Mailgun account and that the base URL matches its region. A 404 here (domain not found) usually means a region mismatch or a domain your account doesn't own; a 401 means an API-key authentication problem — both are distinct from a 400 template/payload error.

Note for Courier users: Courier manages Mailgun template content for you through its own template editor, so you generally don't call Mailgun's Templates API directly — but the same per-domain limits still apply to your underlying Mailgun account.

References

Authoritative sources

DOCSMailgun API Reference — Create a template (POST /v3/{domain}/templates)DOCSMailgun User Manual — Send with Templates (limits: 100 templates, 40 versions)DOCSMailgun API Reference — Create a template version

FAQ

Common questions

Mailgun caps usage at 100 templates per domain (or per account for account-level templates) and 40 versions per template. Mailgun also enforces a maximum size per template — check Mailgun's Help Center for the current figure. Exceeding any of these causes a create or version request to fail.

The name parameter is always required. To create an active, usable template in a single request you must also include template (the content) and, optionally, tag as a version label. Mailgun templates always render with its built-in, customized Handlebars engine — there is no engine-selection parameter; you cannot substitute Mustache, Liquid, etc. Sending only name stores empty metadata with no active version.

Keep going