Troubleshooting & FAQ

PDF & Merge Issues

Form fields not detected

If Mergram doesn’t detect form fields in your PDF:

• Ensure the PDF was created with form-authoring tools (Adobe Acrobat, LibreOffice, etc.)
• Some PDFs have form fields with broken appearance streams — use PDF Form Repair to fix them
• Scanned PDFs (image-only) don’t contain form fields — they need OCR first
• Check that the form fields are not set to “hidden” in the PDF authoring tool

Unicode characters not rendering

If special characters appear as boxes or question marks:

• Upload a custom font that supports the required character set (CJK, Arabic, etc.)
• The default Inter font covers most Latin characters but not all Unicode ranges
• For Vietnamese, Thai, or other complex scripts, use Noto Sans or a dedicated font for that script
• Verify the font you uploaded actually contains the missing glyphs — some fonts have limited character coverage

Merged PDFs are blank or missing content

• Verify that your field positions are within the page boundaries
• Check that your spreadsheet data doesn’t have blank cells where you expect values
• Try a single-row preview first to diagnose the issue
• Ensure the PDF template is not corrupted — try re-uploading the file
• Check that field render types are correct (Text, Image, QR Code, or Barcode)

“Insufficient credits” error

• Check your credit balance in Settings → Credits
• See Credits & Billing for credit costs and purchasing options
• Enterprise deployments have unlimited credits
• Remember that each row costs 1 credit — a 500-row merge requires 500 credits

Large merges are slow

• Server-side merge processing speed depends on template complexity — templates with many fields, custom fonts, or large images take longer per row
• Image fields and custom fonts increase processing time per row
• Avoid extremely large field counts on a single page — each field adds rendering overhead
• If processing is unexpectedly slow, check the job status for any error messages

Email & SMTP Issues

SMTP connection failed

Common causes:

• Wrong host or port — Double-check your SMTP server address and port number
• Firewall — Ensure outbound connections on port 465 or 587 are allowed
• App passwords — Gmail and Outlook require app-specific passwords, not your login password
• SSL/TLS mismatch — Try switching between SSL (port 465) and TLS (port 587)
• Two-factor authentication — If 2FA is enabled, you must use an app-specific password

Emails land in spam

• Configure SPF, DKIM, and DMARC records for your sending domain
• Avoid spam trigger words in the subject line
• Send a test email to yourself first to check deliverability
• Use a reputable SMTP provider (SendGrid, Mailgun, Amazon SES) instead of personal email accounts for large campaigns
• Avoid sending too many emails in a short period — pace your campaigns

Email body formatting issues

• Use the rich text editor for composing email bodies — it ensures valid HTML output
• Test email rendering in different email clients (Gmail, Outlook, Apple Mail)
• Avoid complex HTML structures — stick to basic formatting (paragraphs, bold, italic, lists)
• Use [[ColumnName]] placeholders for personalization — they are replaced before sending

Frequently Asked Questions

What file formats are supported?

Mergram supports PDF and image files (PNG, JPG) for templates, Excel (.xlsx, .xls, .ods), CSV (.csv, .tsv) for data, and any PDF with AcroForm fields for form filling.

What is the maximum number of rows per merge?

You can merge up to 100,000 rows in a single job. Our background worker system handles high-volume processing efficiently.

Can I use the same template with different spreadsheets?

Yes. Templates save your canvas layout and field positions, not the data. Load a template and upload any spreadsheet that has matching column headers.

Is my data secure?

We use industry-standard encryption for data at rest and in transit. Uploaded files and generated PDFs are purged using a configurable retention period.

Can I password-protect the output PDFs?

Yes. Use the password template in the output configuration to encrypt each PDF with a unique password. See the PDF Password Protection guide for details.

Getting more help