ESP Callback Logs
Review ESP Callback Logs to verify and monitor the integration between your system and the Email Service Provider (ESP). These logs provide detailed event data, helping ensure that the connection and responses from the ESP are functioning correctly. When you send emails through third-party ESPs like MumaraOne, Mandrill, SendInBlue, or smtp2go, these providers send callback notifications back to Mumara with delivery status updates, bounce information, and other event data.
Navigate to Tools → Logs → ESP Callbacks to access the callback log browser.
Callback Log Browser
The ESP Callbacks page displays a tree-structured file browser that organizes callback logs by ESP provider. Each provider that you've configured and used to send emails will appear as a folder containing the callback files received from that service.
Provider Folders
The top level of the tree shows folders for each ESP that has sent callback data to your Mumara installation. Folders are created automatically when you integrate an ESP as a sending node and start receiving webhook callbacks from that provider. Each folder is named after the ESP service (for example, MumaraOne, Mandrill, SendInBlue, SMTP2GO, or any other ESP you configure).
If you haven't integrated any ESPs with webhook support, or if the ESPs haven't sent any callbacks yet, the tree will be empty. As you add more ESPs and they begin sending delivery notifications, new folders will appear automatically to organize callbacks by provider.
Click the expand icon (+) next to any folder to view its contents.
Log Files
Inside each provider folder, individual callback events are stored as JSON files. Each file represents a single callback event received from the ESP.
| Element | Description |
|---|---|
| File naming | Files are named using a timestamp format YYYY-MM-DD HH_MM_SS.json indicating exactly when the callback was received - for example, 2024-12-30 13_48_48.json was received on December 30, 2024 at 13:48:48 |
| File icon | Each JSON file is displayed with a document icon, making it easy to distinguish files from folders in the tree structure |
| Chronological order | Files appear in chronological order within each folder, allowing you to review callbacks sequentially |
Click on any JSON file to view its contents in a popup viewer.
Viewing Callback Data
Clicking on a JSON log file opens a modal window displaying the full callback payload received from the ESP.
Callback Viewer Modal
| Element | Description |
|---|---|
| Title bar | Shows the filename followed by "(Response)" to indicate this is the ESP's response data - for example, "2024-12-30 13_48_48.json (Response)" |
| JSON content | The main area displays the raw JSON payload exactly as received from the ESP, formatted for readability with proper indentation |
| Copy button | Copies the entire JSON content to your clipboard for pasting into support tickets, debugging tools, or documentation |
| Close button | Closes the modal and returns to the file browser |
Common Callback Fields
While the exact fields vary by ESP, callback payloads typically include:
| Field | Description |
|---|---|
| type | A code indicating the event type - different ESPs use different codes to represent delivery, bounce, open, click, and other events |
| time_logged | The timestamp when the ESP logged this event on their end, shown in ISO 8601 format with timezone offset |
| time_queued | The timestamp when the message was originally queued for delivery - comparing this with time_logged shows how long delivery took |
| return_path | The bounce address (envelope sender) used for this message - contains encoded information that helps Mumara correlate bounces with the original campaign |
| to | The recipient email address that this callback pertains to - shows who received (or failed to receive) the message |
| org_to | The original "to" address if it was modified during delivery - shows null if the address wasn't changed |
| status | The delivery status as reported by the ESP - common values include "relayed", "delivered", "bounced", "deferred", or "failed" |
| code | The SMTP response code and description - "2.0.0 (success)" indicates successful delivery, while 4xx and 5xx codes indicate temporary or permanent failures |
Understanding Callback Types
ESPs send different types of callbacks based on email events:
| Event Type | What It Means |
|---|---|
| Delivery/Relayed | The email was successfully handed off to the recipient's mail server - this doesn't guarantee inbox placement but confirms the message wasn't rejected |
| Bounce | The email could not be delivered - the callback will include error codes explaining whether it was a hard bounce (permanent) or soft bounce (temporary) |
| Deferred | The email delivery was temporarily delayed - the ESP will retry delivery, and you may see subsequent callbacks with the final status |
| Complaint | The recipient marked the email as spam - this is serious and the contact should be suppressed to protect your sender reputation |
| Open | The recipient opened the email - only available if the ESP tracks opens and is configured to send open callbacks |
| Click | The recipient clicked a link in the email - only available if the ESP provides click tracking callbacks |
Using ESP Callbacks
Verifying ESP Integration
ESP Callbacks help confirm that your sending node integration is working correctly:
- Send a test email through a configured ESP sending node
- Navigate to ESP Callbacks and expand the folder for that ESP
- Look for recent files with timestamps matching your test send
- Review the callback to confirm it shows successful delivery
If no callbacks appear after sending, check that the ESP webhook URL is correctly configured in your ESP account settings.
Troubleshooting Delivery Issues
When emails aren't being delivered:
- Find the relevant timeframe - locate callback files from when the problem occurred
- Review the status and code fields - these indicate what went wrong
- Check for patterns - multiple failures with the same error code suggest a systematic issue
- Correlate with Debug Logs - use the timestamps to find related entries in application logs
Investigating Bounces
When you need to understand why a specific email bounced:
- Search by date and time - find callbacks around when the email was sent
- Look for bounce-type callbacks - status will indicate "bounced" or similar
- Review the error code - the code field explains the bounce reason (invalid address, mailbox full, blocked, etc.)
- Take appropriate action - hard bounces should result in contact suppression, soft bounces may resolve on retry
Best Practices
Regular Monitoring
- Check for new callbacks periodically to ensure ESP integrations are functioning
- Review error patterns - repeated failures to the same domains may indicate blocklisting
- Monitor callback volume - a sudden drop in callbacks could indicate a webhook configuration problem
Callback Management
- Don't delete recent files - keep callback logs for at least 30 days for troubleshooting purposes
- Archive if needed - for compliance requirements, download and archive old callback files before cleanup
- Clean up old logs - very old callback files can be removed to save disk space once no longer needed for reference
Security Considerations
- Callback logs may contain email addresses - treat them as sensitive data
- Restrict access - only administrators who need to troubleshoot delivery issues should access ESP Callbacks
- Don't share raw callbacks publicly - redact email addresses and other personal data if sharing for support purposes
Troubleshooting
No Callbacks Appearing
Possible causes:
- ESP webhook URL is not configured or is incorrect
- ESP account doesn't have webhooks enabled
- Firewall is blocking incoming webhook requests
- The ESP hasn't been used to send emails yet
Solutions:
- Verify the callback/webhook URL in your ESP account settings
- Ensure webhooks are enabled for delivery events in the ESP dashboard
- Check that your server allows incoming HTTP/HTTPS requests from the ESP's IP addresses
- Send a test email through the ESP and wait a few minutes for callbacks to arrive
Callbacks Arriving but Not Processing
Possible causes:
- Callback format doesn't match expected structure
- Database write errors
- Storage permission issues
Solutions:
- Check Debug Logs for errors around the callback timestamp
- Verify the storage directory has write permissions
- Contact Mumara support if callbacks are received but not being parsed correctly
Missing Callback Files
Possible causes:
- Files were manually deleted
- Disk space ran out during callback storage
- The ESP stopped sending callbacks
Solutions:
- Check disk space availability
- Review ESP webhook configuration
- Look in Debug Logs for storage errors
Next Steps
- Debug Logs - View application error logs
- Failed Jobs - Monitor background job failures
- Sending Nodes - Configure ESP sending nodes
- Bounce Addresses - Set up bounce handling