Testing & Troubleshooting HubSpot

After connecting HubSpot to OptiMail, use this guide to verify the integration is working correctly and troubleshoot any issues.

Verifying Your Integration

Check Connection Status

1. Go to Integrations in the left sidebar
2. Look for the HubSpot card
3. Verify the status shows Connected with a green indicator
4. Note the "Last synced" timestamp - it should be recent

Verify Data is Flowing

1. Navigate to your Dashboard
2. Check that you see:
   • Your HubSpot portal name under connected platforms
   • Campaign data populating in the campaigns list
   • Metrics updating in the deliverability overview

Send a Test Email

To verify tracking is working:

1. In HubSpot, send a test email to yourself
2. Wait 5-10 minutes
3. Use the Sync button in OptiMail to refresh data
4. Check OptiMail for the new email campaign
5. Verify the email statistics appear correctly

Common Issues & Solutions

Issue: No Campaigns Appearing

Possible causes:

• Initial sync is still in progress
• No email campaigns have been sent from HubSpot
• Permissions issue with HubSpot

Solutions:

1. Wait 15-30 minutes for the initial sync to complete
2. Click the Sync button to manually refresh data
3. Check your HubSpot portal actually has sent marketing emails
4. Try disconnecting and reconnecting the integration

Issue: Metrics Not Updating

Possible causes:

• Data hasn't been synced yet
• HubSpot API rate limits
• Temporary connection issue

Solutions:

1. Go to Integrations in the left sidebar
2. Click the Sync button on the HubSpot card to manually trigger a data refresh
3. Wait a few minutes and check again
4. If the issue persists, try disconnecting and reconnecting

Issue: Missing Email Events (Opens/Clicks)

Possible causes:

• Email tracking not enabled in HubSpot
• Recipients using email clients that block tracking
• Data hasn't synced yet

Solutions:

1. In HubSpot, verify email tracking is enabled:
   • Go to Settings > Marketing > Email
   • Ensure "Track email opens" and "Track clicks" are enabled
2. Note that some email clients (Apple Mail, Hey, etc.) may block tracking pixels
3. Use the Sync button to refresh data

Issue: Bounce Data Not Accurate

Possible causes:

• Different bounce classifications between platforms
• Delayed bounce processing

Solutions:

1. Allow 24-48 hours for bounce data to fully process
2. Compare specific bounces in both HubSpot and OptiMail
3. Note that OptiMail categorizes bounces as:
   • Hard bounces - Invalid email addresses
   • Soft bounces - Temporary delivery issues
   • Blocked - Rejected by receiving server

Issue: "Reconnection Required" Message

Cause: HubSpot OAuth tokens expire periodically

Solution:

1. Go to Integrations in the left sidebar
2. Click Reconnect on the HubSpot card
3. Re-authorize access in HubSpot
4. Verify the status returns to "Connected"

Issue: Integration Shows "Inactive" Status

Cause: The connection to HubSpot was interrupted. This usually happens when:

• The OptiMail app was uninstalled from HubSpot
• Access permissions were revoked in HubSpot's connected apps
• OAuth token expired and couldn't be refreshed

Important: Your campaign data is preserved when an integration becomes inactive.

Solution:

1. Go to Integrations in the left sidebar
2. Click on the HubSpot integration card
3. Click Reconnect
4. Re-authorize OptiMail in HubSpot
5. Your historical data will be retained and syncing will resume

Issue: Sync Failing with Errors

How to diagnose:

1. Go to Integrations > HubSpot
2. Click on the Sync History tab
3. Find failed sync entries (marked in red)
4. Click to expand and view error details

Common errors:

• Authentication error - Token expired, need to reconnect
• Rate limit exceeded - Too many API requests, wait and retry
• Permission denied - Required scopes missing, reconnect with proper permissions

Viewing Sync Logs

OptiMail keeps detailed logs of all sync operations:

1. Go to Integrations > HubSpot
2. Click the Sync History tab
3. View all sync attempts with:
   • Timestamp
   • Type (Manual or AutoSync)
   • Status (Success/Failed)
   • Duration
   • Campaigns processed

Click any log entry to see detailed information including error messages for failed syncs.

Advanced Troubleshooting

Check API Access

Verify OptiMail's access to your HubSpot portal:

1. Log into HubSpot
2. Go to Settings > Integrations > Connected apps
3. Find "OptiMail" in the list
4. Verify it shows as "Connected" with the correct scopes

Contact Support

If issues persist, contact our support team with:

• Your OptiMail account email
• HubSpot portal ID (found in HubSpot settings)
• Description of the issue
• Screenshots if helpful
• Any error messages you've seen

Best Practices

1. Regular Monitoring - Check your dashboard daily for any anomalies
2. Set Up Alerts - Configure alerts for deliverability drops
3. Review Recommendations - Act on AI-powered suggestions promptly
4. Keep HubSpot Clean - Regular list hygiene improves deliverability
5. Manual Sync - Use the Sync button after sending important campaigns for immediate data refresh

Related Articles

• HubSpot Installation Guide
• Understanding Deliverability Metrics
• Troubleshooting FAQ