converting-email-templates

Files (13)

• SKILL.md
• how-to-migrate-email-templates.md · content/
• conversion-rules.md · references/
• converter.py · scripts/
• brevo-test.html · tests/expected/
• mandrill-mergetags-test.html · tests/expected/
• postmark-test.html · tests/expected/
• sendgrid-test.html · tests/expected/
• brevo-test.html · tests/input/
• mandrill-mergetags-test.html · tests/input/
• postmark-test.html · tests/input/
• sendgrid-test.html · tests/input/
• .gitkeep · tests/output/

SKILL.md (first lines)

# Converting email templates

## Purpose

Automatically convert email templates from other email service providers into Mailtrap-compatible Handlebars syntax. Handles both deterministic pattern conversions (via a Python script) and complex edge cases (via LLM intelligence).

**Related skills:** `using-email-templates` (Handlebars syntax, API template send), `sending-emails` (stream bases and auth), `authorizing-api-requests` (tokens, env vars, `account_id` resolution — needed when creating templates or sending via the Templates API after conversion).

## Input

- **Source provider** (required): `sendgrid`, `mailgun`, `mandrill-handlebars`, `mandrill-mergetags`, `postmark`, `brevo`, or `ses`
- **Input**: a single template file path, a directory of `.html` template files, or raw HTML pasted inline
- **Output directory** (optional): defaults to a `/converted/` subdirectory next to the input

If the user does not specify the source provider, ask before proceeding. If the user provides template HTML inline (pasted in chat), save it to a temporary `.html` file first.

## Workflow

### Step 1: Detect mode

**Fast mode** (default): For providers with deterministic conversion patterns. The Python script handles these reliably.

**Deep mode**: Triggered when:
- Provider is `brevo` AND the template contains nested loops, multiple filters, or complex conditional nesting
- The script flags patterns that could benefit from LLM judgment
- The user explicitly requests deep mode
- Inline HTML is provided (run LLM conversion directly)

### Step 2: Run the converter script

Execute the Python converter script:

```bash
python3 {skill_dir}/scripts/converter.py \
  --provider {provider} \
  --input {input_path} \
  --output {output_dir}
```

Where `{skill_dir}` is the directory containing this SKILL.md file.

**Read the output:**
- Exit code 0: clean conversion, no flags. Proceed to Step 4.
- Exit code 1: conversion completed with flags. Proceed to Step 3.
- Exit code 2: error. Report to user and stop.

Read the `.report.txt` file(s) generated alongside each converted template. For bulk conversions, also read `_summary.txt`.

**Note:** When flags are present, the script automatically:
- Prepends a `<!-- WARNING: ... -->` comment at the top of the converted file
- Wraps unsupported syntax in `<!-- FLAGGED [RULE]: message -->` HTML comments so the file can be pasted into the Mailtrap editor without triggering parser errors

### Step 3: Handle flags (Deep mode)

For each flag in the report:

1. **Read the flagged line** in the original template.
2. **Consult** `references/conversion-rules.md` for the specific rule and recommended action.
3. **Categorize** the flag:
   - **App-layer change required** (e.g., `formatDate`, comparison helpers): Cannot be resolved in the template. Report to the user with a clear explanation of what they need to change in their application code. Suggest the replacement variable name.
   - **Template-level fix possible** (e.g., Brevo nested loops, Mandrill `mc:edit` regions): Apply the conversion using LLM judgment. Show the user the before/after and ask for confirmation before writing.
   - **Ambiguous** (e.g., Postmark closing tag mismatch): Show the user both the original context and the converted output. Ask them to verify.

Present flags grouped by category:
```
## Conversion Complete

### Auto-converted: [count] changes
[Brief summary or collapsed details]

### Needs your application code: [count] flags
[For each: what to change, why, suggested variable name]

### Needs verification: [count] flags
[For each: show before/after, ask for confirmation]
```

### Step 4: Present results

**Single file:**
```
Converted: {filename}
Changes: [count] | Flags: [count]
Output: {output_path}

[Show the conversion report summary]
[If flags exist, show the categorized flag breakdown from Step 3]
```

**Bulk conversion:**
```
Converted: [count] files
Total changes: [count] | Total flags: [count]
Clean: [count] files | Needs review: [count] files
Output: {output_dir}

[Show the summary report]
[List files needing review with their specific flags]
```

### Step 5: API field mapping reminder

After template conversion, always remind the user about the API-side changes they need to make. Reference the quick mapping table:

| Provider | Old template field | Old variables field | Mailtrap field | Mailtrap variables |
|----------|-------------------|--------------------|-----------------------|------------------------|
| SendGrid | `template_id` | `personalizations[].dynamic_template_data` | `template_uuid` | `template_variables` |
| Mailgun | `template` | `t:variables` | `template_uuid` | `template_variables` |
| Mandrill | `template_name` | `global_merge_vars` + `merge_vars` | `template_uuid` | `template_variables` |
| Postmark | `TemplateId`/`TemplateAlias` | `TemplateModel` | `template_uuid` | `template_variables` |
| Brevo | `templateId` | `params` | `template_uuid` | `template_variables` |
| Amazon SES | `TemplateName`/`TemplateArn` | `TemplateData` | `template_uuid` | `template_variables` |

Only show the row for the provider that was just converted.

## Inline conversion (no file)

If the user pastes template HTML directly in chat instead of providing a file path:

From mailtrap/mailtrap-skills, MIT.

More from mailtrap/mailtrap-skills