Troubleshooting

SMTP Authentication Failures

"535 Username and Password not accepted"

This is the most common Gmail error. It means you are using your regular Google account password instead of an App Password. Gmail blocks plain password auth for accounts with 2-Step Verification.

Fix: Generate an App Password at myaccount.google.com/apppasswords and use that 16-character password in MergeMail.

"Connection timeout" or "ECONNREFUSED"

The SMTP host or port is unreachable. This often happens when using port 25, which is blocked by most cloud providers.

Fix: Use port 587 with STARTTLS (recommended) or port 465 with SSL/TLS. Never use port 25.

"EAUTH Invalid credentials"

Credentials are syntactically accepted but authentication failed. Double-check the username (full email address, not just the local part) and password.

"TLS required but not available"

Your SMTP server requires TLS but you selected the wrong security mode.

Fix: Switch the security setting to STARTTLS or SSL/TLS depending on your provider.

Document Generation Issues

"Placeholder not found in template"

A placeholder in your template does not match any mapped column. Common causes: typo in the placeholder name, extra space inside the braces (e.g. {{ name }} instead of {{name}}), or the column was renamed after mapping was saved.

Fix: Open the template editor, verify all placeholder names match your spreadsheet columns exactly (after normalization).

Generated DOCX looks wrong / formatting is broken

This can happen when a placeholder spans multiple formatting runs in Word. For example, typing {{first then bolding it then typing _name}} creates two separate XML runs.

Fix: Delete the entire placeholder and retype it as a single operation. Do not mix formatting styles mid-placeholder.

PDF form fields not filling

If a PDF field is named differently from the spreadsheet column, it will not be filled.

Fix: In your PDF editor, rename the form field to match the normalized column name exactly (lowercase, underscores, no special characters).

Spreadsheet / Dataset Issues

"Invalid email address in row N"

A cell in the email column contains a value that is not a valid email address (e.g. a name, phone number, or malformed address).

Fix: Open the spreadsheet, correct or remove the invalid email address in row N, and re-upload.

Column headers not detected

If MergeMail shows no columns or incorrect columns, the spreadsheet may have data in row 1 without a header row, or the file may have merged cells.

Fix: Ensure row 1 contains column headers. Remove all merged cells. Save as a plain XLSX or CSV.

Special characters appearing as "?" or garbled text

CSV files saved with a non-UTF-8 encoding (e.g. Windows-1252) may have characters like "é", "ñ", or "ₙ" garbled.

Fix: Save the CSV with UTF-8 encoding. In Excel: File → Save As → select CSV UTF-8 (with BOM). In LibreOffice: check the UTF-8 option in the CSV export dialog.

ZIP Upload Issues

"ZIP bomb detected"

The ZIP file's decompressed size exceeds the 500 MB safety limit. This is a security measure, not an error on your part if the file is legitimate.

Fix: Split the archive into multiple smaller ZIPs and create a separate matching import for each.

"File path traversal detected"

A file inside the ZIP has a path that starts with ../. This is a security block.

Fix: Re-create the ZIP with files at the root level only. Most GUI zip tools do this by default when you select files and zip them.

Credit Deduction Questions

"My balance was deducted but the email shows as failed"

MergeMail deducts a credit when the SMTP server accepts the message (returns a 250 response). If the SMTP server accepted it but the email was later bounced by the recipient's mail server, that is an external event MergeMail cannot detect. The credit is not automatically refunded in this case.

However, if the SMTP server rejected the message during the delivery attempt (a non-250 response), the credit is automatically refunded.

"Credits are reserved but the campaign is stuck"

This can happen if a campaign enters an unexpected error state. Contact support with the campaign ID and we will investigate and release the reserved credits if appropriate.