Troubleshooting
Dispatch is designed to fail loudly and predictably. When something goes wrong, it’s usually due to SMTP, or cron execution.
SMTP connection failed
Symptoms: SMTP test fails or campaigns immediately enter “Failed” status.
- Verify SMTP host, port, username, and password
- Ensure encryption matches the port (TLS: 587, SSL: 465)
- Check that your hosting provider allows outbound SMTP connections
- Try alternative ports such as 2525 if standard ports are blocked
- Confirm your SMTP credentials work outside WordPress (mail client or CLI test)
Emails go to spam or never arrive
Symptoms: Messages are sent successfully but do not appear in inboxes.
- Check spam or junk folders
- Verify SPF and DKIM are configured for the sending domain
- Ensure the “From” address matches the authenticated domain
- Start with low sending rates and ramp up gradually
- Avoid URL shorteners and overly promotional subject lines
Visual Builder not loading
Symptoms: Blank builder screen, loading spinner never completes, or JavaScript errors.
- Hard refresh the page (Ctrl / Cmd + Shift + R)
- Check the browser console for JavaScript errors
- Disable other plugins temporarily to test for conflicts
- Ensure your theme does not block admin scripts
- Confirm all Dispatch assets are present in the plugin directory
Subscribers not receiving confirmation emails
Symptoms: Users submit the signup form but never receive confirmation.
- Verify SMTP configuration and send a test email
- Check spam folders
- Ensure confirmation templates include
{{CONFIRMATION_URL}} - Confirm subscriber status is “Pending” and not already confirmed
- Review Dispatch logs for confirmation send attempts
Campaign stuck in “Sending”
Symptoms: Campaign status remains “Sending” with no progress, or emails send very slowly.
- Confirm WP-Cron is enabled (
DISABLE_WP_CRONshould not be set to true) - Visit the site frontend to trigger WP-Cron manually
- If possible, configure a real system cron to call
wp-cron.php - Verify sending limits are not set extremely low (example: 1 email per hour)
- Check Dispatch logs for queue or SMTP errors
Unsubscribe links not working
Symptoms: Clicking unsubscribe results in an error or does nothing.
- Ensure templates include
{{UNSUBSCRIBE_URL}} - Check permalink settings (pretty permalinks recommended)
- Verify no security plugin is blocking the unsubscribe endpoint
- Confirm the campaign email was sent by Dispatch (not forwarded)
Database tables missing
Symptoms: Errors related to missing tables or empty data views.
- Deactivate and reactivate the plugin to trigger table creation
- Confirm the database user has CREATE and ALTER permissions
- Check for table prefix mismatches
- Review Dispatch logs for database errors
Still stuck?
If a problem persists, collect the relevant log entries, note your WordPress version, PHP version, and SMTP provider, then contact support. Most issues can be diagnosed quickly with that information.
Dispatch
Self-hosted email campaigns for WordPress: list management, sending controls, compliance tools, and privacy-first defaults.
