✉️ Email Template Troubleshooting Guide
Easy Form Builder by WhiteStudio — Email Delivery & Rendering
Version 4.0
1. How Email Templates Work
Easy Form Builder uses a drag-and-drop email template builder that stores design data in a JSON structure called EFBDATA.
When a form is submitted, the plugin reads the EFBDATA, renders each block into email-safe HTML (using tables, inline styles, and VML for Outlook), and sends the result via wp_mail().
Rendering Pipeline
→
→
→
→
2. Email Block Reference
The email template builder supports the following blocks. Each block is rendered as email-safe table-based HTML with inline CSS.
| Block | Description | Client Compatibility |
|---|---|---|
| Header | Top section with background color/gradient. Can contain Logo and Title as children. | ✅ All clients (gradient has solid fallback for Outlook) |
| Logo | Displays an image (site logo). Supports width, alignment, and alt text. | ✅ All clients |
| Title | Heading text with customizable font, size, weight, color, and alignment. | ✅ All clients |
| Text | Paragraph text with font, color, line-height, and padding options. | ✅ All clients |
| Message | Dynamic form submission content. Replaced with actual form data at send time. | ✅ All clients |
| Button | Call-to-action button with link, colors, and border radius. Uses VML for Outlook. | ✅ All clients (VML fallback for Outlook) |
| Divider | Horizontal line separator with color, thickness, and width options. | ✅ All clients |
| Spacer | Empty vertical space with configurable height. | ✅ All clients |
| Image | Displays a hosted image. Supports width, alt text, alignment, and optional link. | ✅ All clients (requires publicly hosted image URL) |
| Columns | Two-column layout for side-by-side content. Table-based for email compatibility. | ✅ All clients (stacks on mobile) |
| Social | Social media icon links (Facebook, X, Instagram, etc.) with customizable color. | ✅ All clients (PNG-based icons) |
| Footer | Footer text section with color, font, alignment, and background options. | ✅ All clients |
| HTML Block | Raw HTML injection. Content is rendered as-is without processing. | ⚠️ Depends on the HTML you write |
3. Global Settings
Global settings apply to the entire email template and affect all blocks.
| Setting | Default | Description |
|---|---|---|
| Background Color | #f8f9fa |
Outer background color of the entire email |
| Content Background | #ffffff |
Background color of the content area (inner card) |
| Content Width | 600px |
Maximum width of the email content. 600px is the industry standard for email. |
| Border Radius | 8px |
Rounded corners for the content area. Ignored by Outlook. |
| Font Family | Segoe UI, Tahoma, etc. | Default font for all text blocks. Web fonts are not supported — use system fonts. |
| Direction | Auto-detected (LTR/RTL) | Text direction. Automatically set based on your WordPress locale. |
| Button Background | #202a8d |
Default background color for all button blocks |
| Button Text Color | #ffffff |
Default text color for all button blocks |
4. Email Delivery Issues
❌ Problem: Emails Are Not Being Sent at All
Cause: WordPress uses the PHP mail() function by default, which may be disabled or misconfigured on your hosting.
Solution:
- Install an SMTP plugin such as WP Mail SMTP, Post SMTP, or FluentSMTP
- Configure the SMTP plugin with your email provider’s settings (Gmail, Outlook, SendGrid, etc.)
- Use the SMTP plugin’s test feature to send a test email and verify delivery
- Check your WordPress error log at
wp-content/debug.logfor any PHP mail errors
❌ Problem: Emails Sent But Not Received
Cause: The email is being sent by WordPress but is rejected or filtered by the recipient’s email provider.
Solution:
- Check the recipient’s spam/junk folder
- Verify that your domain has proper SPF, DKIM, and DMARC DNS records configured
- Avoid using a free email address (gmail.com, yahoo.com) as the “From” address — use your own domain
- Contact your hosting provider to confirm outbound email is not blocked on port 25/587
❌ Problem: Emails Are Delayed
Cause: Some hosting providers queue email and send it in batches, or the SMTP server has rate limits.
Solution:
- Use a dedicated transactional email service (SendGrid, Mailgun, Amazon SES) for reliable and fast delivery
- Check if your hosting has email sending rate limits and adjust accordingly
mail() function is unreliable on most shared hosting environments.
5. Rendering Across Email Clients
Different email clients have vastly different HTML/CSS support. Here is what to expect:
| Feature | Gmail | Outlook (Desktop) | Apple Mail | Yahoo |
|---|---|---|---|---|
| Inline CSS | ✅ | ✅ | ✅ | ✅ |
| Background Color | ✅ | ✅ | ✅ | ✅ |
| CSS Gradients | ✅ | ❌ (solid fallback) | ✅ | ✅ |
| Border Radius | ✅ | ❌ (square corners) | ✅ | ✅ |
| Web Fonts | ❌ | ❌ | ✅ | ❌ |
| SVG Images | ❌ | ❌ | ✅ | ❌ |
| PNG Images | ✅ | ✅ | ✅ | ✅ |
| VML (Vector Markup) | ❌ | ✅ | ❌ | ❌ |
| Max-width | ✅ | ❌ (uses MSO tables) | ✅ | ✅ |
6. Header Block Issues
❌ Problem: Header Gradient Shows as Solid Color in Outlook
Cause: Microsoft Outlook (desktop) uses the Word rendering engine, which does not support CSS gradients.
Solution: This is expected behavior. The plugin automatically extracts the first color from your gradient and uses it as a solid background fallback for Outlook. The gradient will display correctly in Gmail, Apple Mail, Yahoo, and web-based clients.
❌ Problem: Header Background Color Not Showing
Cause: Dark mode in email clients can override background colors.
Solution:
- This is controlled by the email client and cannot be overridden by the sender
- Choose colors that remain readable in both light and dark mode
- Test your email by sending a preview to yourself and checking dark mode on your phone
7. Logo Block Issues
❌ Problem: Logo Image Not Displaying
Cause: The logo image URL is not publicly accessible, or images are blocked by the email client.
Solution:
- Ensure the logo is uploaded to your WordPress Media Library (not an external URL that may be blocked)
- Verify the image URL is accessible from outside your network — open it in an incognito browser window
- If your site uses HTTP (not HTTPS), some email clients may block the image. Use HTTPS.
- Some email clients block images by default until the user clicks “Display images.” Include a descriptive alt text so the user knows what the image is.
❌ Problem: Logo Appears Too Large or Too Small
Cause: The logo width setting in the builder does not match the actual image dimensions.
Solution: Adjust the width setting in the Logo block properties. The recommended logo width for email is between 100px and 200px.
8. Text & Title Block Issues
❌ Problem: Font Not Matching the Builder Preview
Cause: Email clients do not support web fonts. The font visible in the builder may not be available on the recipient’s device.
Solution:
- Use system-safe fonts: Arial, Verdana, Tahoma, Georgia, Segoe UI, Trebuchet MS
- The fallback font stack ensures readability even when the primary font is unavailable
❌ Problem: Text Color Looks Different in Dark Mode
Cause: Gmail, Outlook, and Apple Mail have dark mode features that can invert or modify text and background colors.
Solution:
- Avoid very light text on white backgrounds (it becomes invisible in dark mode)
- Use sufficient contrast between text and background colors
- Test by enabling dark mode on your email client before sending to your users
❌ Problem: RTL Text Appearing as LTR
Cause: The email direction setting does not match the content language.
Solution: The plugin automatically detects RTL from your WordPress locale. If your content is in Arabic, Persian, or Hebrew, ensure WordPress is set to the correct locale in Settings > General > Site Language.
9. Message Block Issues
❌ Problem: Message Block Shows “shortcode_message” Instead of Form Data
Cause: The form submission data was not properly passed to the email renderer.
Solution:
- Ensure the form has at least one field (e.g., name, email, or message)
- Verify that the form is properly saved and published
- Check
wp-content/debug.logfor any PHP errors related to form submission - Try re-saving the email template in the Email Template Builder
❌ Problem: Form Data Appears But Is Not Formatted
Cause: The message block renders the form data as-is. Complex HTML in form responses may not be styled.
Solution: The Message block applies the font, color, and alignment settings from its properties panel. Adjust these settings in the builder to match your design.
10. Button Block Issues
❌ Problem: Button Has White Background and White Text in Outlook
Cause: Older versions of the plugin used CSS-only buttons that Outlook’s Word-based renderer could not display.
Solution: This has been fixed. The plugin now uses VML (Vector Markup Language) to render buttons in Outlook. Buttons will display with the correct background color and text color in all Outlook versions. Ensure you are using version 4.0 or later.
❌ Problem: Button Background Color Stripped in Gmail
Cause: Gmail strips CSS gradient backgrounds from links.
Solution: The plugin uses a solid background-color instead of gradients for buttons. This ensures consistent rendering in Gmail and all other clients. If your button still appears without a background, re-save the email template to apply the latest rendering code.
❌ Problem: Button Border Radius Not Showing in Outlook
Cause: Outlook does not support CSS border-radius.
Solution: The VML fallback for Outlook uses arcsize to approximate rounded corners. However, the result may not be pixel-perfect compared to other clients. This is a known Outlook limitation.
❌ Problem: Button Color Does Not Match the Builder
Cause: The button uses the Global Settings for button background and text color.
Solution: Check the Global Settings panel in the email template builder. The “Button Background” and “Button Text Color” settings control the default colors for all buttons.
11. Image Block Issues
❌ Problem: Image Not Displaying in the Email
Cause: The image URL is not publicly accessible, or the email client blocks images by default.
Solution:
- Upload images to your WordPress Media Library. Do not use
localhostURLs — they are not accessible from the recipient’s email client. - Ensure your site uses HTTPS. Many email clients block images served over HTTP.
- Open the image URL in a private browser window to confirm it loads.
- Add descriptive alt text so users see meaningful information while images are loading.
❌ Problem: Image Is Too Wide on Mobile
Cause: The image width exceeds the screen size on mobile devices.
Solution: The plugin includes a responsive CSS rule (max-width: 100%) that scales images down on mobile. If you are using a percentage-based width (e.g., 100%), images will automatically fit the container.
❌ Problem: Image Link Not Clickable
Cause: The image link field in the builder is empty or contains an invalid URL.
Solution: Open the Image block settings and verify the link URL starts with https://.
12. Divider & Spacer Issues
❌ Problem: Divider Not Visible
Cause: The divider color is too similar to the content background color.
Solution: Change the divider color in the block settings to create more contrast with the background. Also check that the divider thickness is at least 1px.
❌ Problem: Spacer Height Ignored in Outlook
Cause: Some versions of Outlook collapse empty table cells.
Solution: The plugin uses a character inside spacer cells to prevent collapsing. If the spacer still appears shorter than expected in Outlook, try increasing the height slightly.
13. Columns Block Issues
❌ Problem: Columns Not Side-by-Side in Outlook
Cause: Outlook sometimes does not respect percentage-based table widths correctly.
Solution: The plugin uses a table-based layout (48% | 4% gap | 48%) that Outlook supports. If columns still stack, the content in one column may be too wide. Keep column content concise.
❌ Problem: Columns Stack on Mobile
Cause: This is intentional responsive behavior. On screens narrower than 600px, columns stack vertically for readability.
Solution: No action needed. This is the correct behavior for mobile devices.
16. HTML Block Issues
❌ Problem: Custom HTML Not Rendering Correctly
Cause: Email clients have very limited HTML/CSS support compared to web browsers.
Solution:
- Use only table-based layouts instead of
div/flexbox/grid - Use only inline CSS (
style="..."). Email clients strip<style>blocks and external stylesheets. - Do not use
<script>tags — JavaScript is stripped by all email clients - Do not use SVG images or base64-encoded images — Gmail and Outlook will not display them
- Use absolute URLs for all images (e.g.,
https://yourdomain.com/image.png)
Safe Tags for Email HTML Block
| Safe to Use | Avoid |
|---|---|
<table>, <tr>, <td>, <th> |
<div> with complex CSS |
<p>, <h1>–<h6>, <span> |
<section>, <article>, <nav> |
<a>, <img>, <br> |
<svg>, <canvas>, <video> |
<strong>, <em>, <b>, <i> |
<script>, <style>, <link> |
<ul>, <ol>, <li> |
<form>, <input>, <button> |
17. Emails Going to Spam
❌ Problem: Emails Consistently Land in Spam Folder
Cause: Multiple factors can trigger spam filters.
Solution: Check and address each of the following:
| # | Check | How to Fix |
|---|---|---|
| 1 | SPF Record | Add an SPF DNS record for your domain that includes your mail server. Example: v=spf1 include:_spf.google.com ~all |
| 2 | DKIM Signature | Configure DKIM through your email provider or SMTP plugin. This adds a digital signature to prove the email is from your domain. |
| 3 | DMARC Policy | Add a DMARC DNS record: v=DMARC1; p=quarantine; rua=mailto:[email protected] |
| 4 | From Address | Use a “From” email that matches your domain (e.g., [email protected]), not a free email like @gmail.com |
| 5 | Email Content | Avoid spam trigger words (“free”, “urgent”, “click here”, excessive exclamation marks, ALL CAPS text) |
| 6 | Image-to-Text Ratio | Do not send image-only emails. Include meaningful text content alongside images. |
| 7 | Blacklist Check | Check if your domain or server IP is blacklisted at mxtoolbox.com/blacklists |
18. Debugging Checklist
Use this checklist when troubleshooting email issues:
| # | Check | Expected |
|---|---|---|
| 1 | WordPress can send email | Install an SMTP plugin and send a test email successfully |
| 2 | Email template is saved | Open the form > Email Template Builder > Save. Check that blocks appear in the preview. |
| 3 | Images are publicly accessible | Open image URLs in an incognito browser window. They must load without login. |
| 4 | No PHP errors | Enable WP_DEBUG and WP_DEBUG_LOG in wp-config.php and check wp-content/debug.log |
| 5 | Social icons exist | Check public/assets/images/social/ folder has PNG files in the plugin directory |
| 6 | Uploads directory is writable | Check wp-content/uploads/ has write permissions (755 or 775) |
| 7 | HTTPS is enabled | Your site URL should start with https://. Mixed content (HTTP images in HTTPS emails) may be blocked. |
| 8 | Email not clipped by Gmail | Keep email HTML under 102 KB. Remove unnecessary blocks if Gmail shows “[Message clipped]”. |
🐛 Enable WordPress Debug Logging
Add the following to your wp-config.php file (before the line “That’s all, stop editing!”):
define(‘WP_DEBUG_LOG’, true);
define(‘WP_DEBUG_DISPLAY’, false);
After enabling, submit a form and check the log file at wp-content/debug.log for any errors.
WP_DEBUG on production sites after troubleshooting. Leaving it enabled can expose sensitive information and slow down your site.
WhiteStudio.team
14. Social Block Issues
❌ Problem: Social Icons Not Showing in Emails
Cause: Social icons are rendered as PNG images hosted on your server. If the server is not publicly accessible (e.g., localhost, staging behind a firewall), the email client cannot load the images.
Solution:
public/assets/images/social/wp-content/uploads/directory is writable (the plugin caches recolored icons there)❌ Problem: Social Icons Show Wrong Color
Cause: The icon color was changed in the builder but the cached colored icon was not regenerated.
Solution:
wp-content/uploads/efb-icons/wp-content/uploads/efb-icons/folder. The plugin will regenerate the icons on the next email send.❌ Problem: Some Social Icons Missing, Others Display Fine
Cause: A specific icon PNG file may be missing from the plugin directory.
Solution:
public/assets/images/social/{icon-name}.pngexists for the missing iconSupported Social Icons
facebookxinstagramlinkedinyoutubetiktokwhatsapptelegrampinterestsnapchatgithubdribbbleredditdiscordtwitchmediumspotifybehancevimeowebsiteemail