Step by step guide to creating and managing email templates in Mailgun

If you’re sending emails programmatically, you’ll hit a wall fast if you’re copying and pasting message content everywhere. That’s where email templates come in—they keep things tidy, reusable, and less prone to mistakes. This guide is for developers, ops folks, and anyone who needs to wrangle transactional or marketing emails using Mailgun. I’ll walk through setting up, managing, and tweaking templates so you don’t have to dig through outdated docs or guess at best practices.

Let’s skip the fluff and get straight to what works.

Why bother with templates in Mailgun?

Before we jump into the how-to, here’s the honest pitch: Templates save time and reduce mistakes. Instead of hardcoding email content in your app or scripts, you keep a single source of truth in Mailgun. This makes it way easier to update messages, handle translations, and personalize content. If you’re dealing with more than one email type—or want to avoid embarrassing typos going out to thousands of users—templates are worth it.

Mailgun’s template system isn’t the fanciest, but it’s reliable and gets the job done. Just don’t expect a drag-and-drop builder or fancy AI. This is a developer tool, and that’s okay.

Step 1: Set up your Mailgun account (if you haven’t already)

If you’re already sending emails through Mailgun, skip ahead. If not:

  • Sign up for a Mailgun account. You’ll need a verified domain, so budget time for DNS setup.
  • Verify your sending domain. This means adding TXT and MX records—Mailgun’s dashboard walks you through it, but DNS changes can take a while to propagate.
  • Get your API key. You’ll use this for authenticating API requests later.

Pro tip: Use a dedicated sending domain (like mail.example.com) instead of your root domain. It keeps your main domain’s reputation safer.

Step 2: Understand how Mailgun templates work

Mailgun templates are basically named blobs of HTML (and optional plain text) with placeholders for variables. You store them in Mailgun, then reference them when sending emails via the API.

  • Variables: Use {{variable_name}} syntax in your templates. You’ll pass values for these when sending.
  • Versions: You can keep multiple versions of a template—good for A/B testing or localization.
  • No WYSIWYG: You edit templates as raw HTML/text. If you want visual editing, you’ll need to build elsewhere and paste in.

What doesn’t work: There’s no built-in image hosting or asset management. Host images elsewhere and use absolute URLs.

Step 3: Create your first template

You can create templates via the Mailgun web dashboard or the API. The dashboard is fine for a couple templates; use the API if you’re automating or managing at scale.

A. Using the Mailgun dashboard

  1. Log in and pick your domain.
  2. In the sidebar, click Sending > Templates.
  3. Hit the Create Template button.
  4. Give your template a clear, unambiguous name. Something like user_welcome or receipt_v2.
  5. Choose a template type:
    • HTML & Text is safest—some clients only display plain text.
  6. Paste your HTML and/or text content. Use {{variable}} for anything dynamic (name, link, etc.).
  7. Save.

Tip: Test your HTML elsewhere (e.g., Litmus or Email on Acid) before pasting it into Mailgun. Their editor won’t catch rendering bugs.

B. Using the Mailgun API

If you like automating things, here’s how to add a template with curl:

bash curl -s --user 'api:YOUR_API_KEY' \ https://api.mailgun.net/v3/YOUR_DOMAIN/templates \ -F name='user_welcome' \ -F description='Welcome email for new users' \ -F template='Hello {{first_name}}, welcome!'

  • Replace YOUR_API_KEY and YOUR_DOMAIN as needed.
  • The template field is your HTML. Use single quotes to avoid shell issues.

Caveat: The API isn’t as forgiving with formatting—double-check for escaped characters and syntax errors.

Step 4: Add variables and personalize content

Templates are only useful if you can personalize them. Mailgun uses {{variable}} placeholders, which you fill in when sending.

  • Example: In your template: Hello {{first_name}},
  • When sending, provide: { "first_name": "Ada" }

You can nest variables or use simple logic with the Handlebars templating syntax (that’s what Mailgun supports).

What to avoid: Don’t get too clever with logic in templates. Keep conditions simple. Complex workflows are better handled in your app.

Step 5: Test your template

Don’t skip this, even if you’re in a hurry.

  • Use Mailgun’s “Send Test” button in the dashboard, or
  • Hit the API with a test call, passing sample variables.

Example API call:

bash curl -s --user 'api:YOUR_API_KEY' \ https://api.mailgun.net/v3/YOUR_DOMAIN/messages \ -F from='hello@example.com' \ -F to='your@email.com' \ -F subject='Test Email' \ -F template='user_welcome' \ -F 'h:X-Mailgun-Variables={"first_name":"Ada"}'

Watch out for: Typos in variable names. If you forget to supply a variable, Mailgun won’t throw an error; it’ll just leave the placeholder blank or show {{first_name}} in the email. Always check your test sends.

Step 6: Manage and update templates

Things change—copy tweaks, branding updates, new features. Here’s how to keep templates under control.

Editing templates

  • In the dashboard, find your template, click Edit, make your changes, and save.
  • You can create new versions of a template (like v2, v3). This lets you roll back if you break something.

Deleting templates

  • Only delete if you’re 100% sure it’s not referenced anywhere. There’s no “undelete.”
  • You can “archive” templates by renaming or moving them out of rotation, but Mailgun doesn’t have a soft-delete.

API management

All the above can be done via API (list, update, delete). Handy if you’re syncing templates from source control.

Pro tip: Keep your “source of truth” for email templates in version control (like Git), not just in Mailgun. This helps with team collaboration and disaster recovery.

Step 7: Organize templates as your needs grow

A few templates are easy to keep straight. Once you’ve got a dozen or more, things can get messy.

Practical tips: - Naming conventions: Use clear, predictable names (e.g., receipt_v2, password_reset_en, order_shipped_fr). Consistency saves headaches. - Document variables: Keep a simple doc or spreadsheet listing each template and the variables it expects. Future you will thank you. - Versioning: Don’t be afraid to create a new template version rather than editing live. If you’re doing A/B tests, name variants clearly.

What to ignore: Don’t bother with elaborate folder structures—Mailgun doesn’t support them. Keep it simple and rely on naming.

Step 8: Use templates in your app or backend

Once templates are set up, your code only needs to reference the template name and pass variables.

Example with Python (using requests):

python import requests

api_key = "YOUR_API_KEY" domain = "YOUR_DOMAIN" template = "user_welcome" variables = {"first_name": "Ada"}

resp = requests.post( f"https://api.mailgun.net/v3/{domain}/messages", auth=("api", api_key), data={ "from": "hello@example.com", "to": "ada@example.com", "subject": "Welcome!", "template": template, "h:X-Mailgun-Variables": json.dumps(variables), } ) print(resp.status_code, resp.text)

  • Swap out the placeholders for your own data.
  • You can use any language—Mailgun’s API is just HTTP.

Reality check: If you’re changing templates often or have multiple environments (dev, staging, prod), build some checks into your deployment pipeline. It’s easy to get out of sync.

Step 9: Monitor deliverability and troubleshoot

Templates won’t fix deliverability issues, but they can help by keeping your emails consistent.

  • Use Mailgun’s logs to see if emails are sent and delivered.
  • Watch for bounces or spam complaints—bad HTML or broken links can hurt your reputation.
  • If you see template errors, double-check your variable names and values.

Don’t chase every error: Some bounces are normal. Focus on patterns, not isolated cases.

Things to know (and ignore)

  • No built-in preview for every client. Test important templates yourself in major email clients (Gmail, Outlook, Apple Mail).
  • No template sharing across domains. Each Mailgun domain has its own set of templates.
  • No built-in translations. You manage different language templates manually (e.g., welcome_en, welcome_fr).
  • Ignore fancy features. Stick to basic templating unless you really need more.

Wrap-up

Mailgun’s template system is simple, and that’s its strength. Don’t overcomplicate things: keep templates clear, version changes, and document your variables. Set up a solid naming scheme early, and automate what you can. It’s easy to get lost in the weeds, but the fastest way to improve is to start simple and tweak as you go.

You don’t need more tools. Just keep your templates clean and your process straightforward. You’ll spend less time on email and more time on things that matter.