Troubleshooting

This page covers common issues across both Dispatch Core and Dispatch Pro functionality. Start with the Core issues if you’re experiencing sending problems — many of them have the same root causes regardless of which version you’re on.

SMTP errors / emails not sending

Go to Dispatch → Settings and verify your SMTP credentials — hostname, port, username, password, and encryption type
Test the connection using the built-in test button before launching a campaign
Common mistakes: using port 587 with SSL (use TLS), leaving the password field empty after a password change
If your provider requires an app password (Gmail, Outlook), use that — not your account password
Check your SMTP provider’s dashboard for authentication errors or rate limit blocks

Emails landing in spam

Check that SPF, DKIM, and DMARC records are properly configured for your sending domain
Make sure your “From” address matches the domain your SMTP account is authorized to send from
Avoid spam trigger words in subject lines; don’t use all-caps; include plain-text fallback content
All subscribers should be double opt-in verified — sending to unconfirmed addresses increases spam complaints
Include your physical mailing address in campaign emails as required by CAN-SPAM

Send queue stalled

Dispatch uses WP-Cron to process the send queue — if WP-Cron is disabled or unreliable, the queue will stall
Check if DISABLE_WP_CRON is set to true in your wp-config.php
If your host uses server-side cron, make sure the WP-Cron endpoint is being called regularly
A long-running plugin or heavy page load can also delay cron execution — check for PHP memory or timeout issues

Confirmation emails not being received

Check the subscriber’s spam/junk folder first
Verify the transactional email is enabled at Dispatch → Transactional Emails
Use the test send button on the Confirmation email to verify delivery to your own inbox
Confirm SMTP is working correctly (see SMTP section above)

Unsubscribe link returns 404

Go to Settings → Permalinks and click Save (this flushes rewrite rules)
Make sure the Dispatch plugin is active — the unsubscribe endpoint is registered by the plugin

License won’t activate

Double-check your license key for typos — copy and paste directly from your purchase email
Your license is tied to a specific domain. If your site’s domain does not match the domain registered with the license, activation will fail
If you have previously activated this license on another domain, deactivate it there first before activating on the new domain
If the activation request times out, check that your server can reach the license server outbound — some hosting environments block external HTTP requests

Visual Builder not opening

Open your browser’s developer console (F12) and look for JavaScript errors
A conflict with another admin plugin is the most common cause — try deactivating plugins one by one to isolate the conflict
Switch to Chrome if you’re using Firefox or Safari as a first diagnostic step; Chrome has the best compatibility with the GrapesJS editor

Visual Builder content not saving

Check the browser console for errors when clicking Save in the builder
If the modal closes but the campaign editor shows no content, try refreshing the page and reopening the builder
As a fallback, switch the editor mode to Raw HTML and paste your HTML directly

Transactional emails not sending

Confirm that Dispatch Core is active — transactional sends depend on Core’s SMTP configuration
Verify SMTP settings are working via the test button at Dispatch → Settings
Use the Send Test button on each transactional email screen to verify delivery
Check that the specific email (Welcome, Unsubscribe Confirmation) is enabled at Dispatch → Transactional Emails

CSV import not working

File must be UTF-8 encoded with comma delimiters
First row must be a header row containing email (required) and optionally first_name
If the upload fails silently, check your PHP upload_max_filesize and post_max_size settings — large files may be rejected by the server before reaching the plugin
If rows are skipped, they may contain invalid email addresses or addresses that already exist in your subscriber list

Gmail dark mode color issues

Dispatch Pro injects color-scheme: light only meta tags and CSS as a best-effort fix for Gmail Android dark mode color inversion. This addresses most color problems, but Gmail Android’s dark mode rendering is inconsistent and not fully controllable by email senders. See the Known Limitations page for details.

White screen or fatal error after activation

Enable WordPress debug mode by adding define('WP_DEBUG', true); to wp-config.php and refreshing
Check /wp-content/debug.log for the specific error
Confirm your server meets all requirements — particularly PHP 7.4 or higher and the openssl and mbstring extensions
Deactivate all other plugins and switch to a default theme, then reactivate Dispatch to rule out a plugin or theme conflict

Dispatch Pro

Premium self-hosted email marketing for WordPress. Everything in Core, plus the Visual Builder, customizable transactional emails, and CSV import/export.

Quick Links

Need support?

Dispatch Pro Support →

Troubleshooting