Bounced email management in SuiteCRM is not super well documented and what happens when emails bounce or how they get “bounced” is not very intuitive. Thankfully, I’ve explored this topic in detail so you don’t have to. All the questions you’ll probably have about email bounces in SuiteCRM will be answered in this complete walkthrough of SuiteCRM email bounce handling.
What is a Bounce Handling Account
A bounce account is a special email account that is used to handle bounced emails from a campaign. A bounced email is an email that cannot be delivered to the recipient for some reason, such as an invalid address, a full mailbox, or a server error. When you send a campaign, you can specify a bounce account to receive the notifications of bounced emails from the email servers. SuiteCRM will then process these notifications and update the status of the campaign email addresses accordingly. Note that the bounce account is not the reply to (although you may set it up this way).
How to Setup a Bounce Handling Account
To set up a bounce account, you need to have an administrator role in SuiteCRM. You can create a bounce account from the Email Settings section of the Administration panel. You need to provide the email address, password, and server settings for the bounce account. You can use any email address that you have access to, but it is recommended to use a dedicated address for this purpose, such as bounce@domain.com. You also need to select the option “Bounce Handling Account” when creating the account.
Once you have created a bounce account, you can use it in your campaigns. When you create a campaign, you can select the bounce account from the drop-down menu in the Campaign Email Settings step. This will tell SuiteCRM to use this account to handle the bounced emails from this campaign. You can also specify a different reply-to address for your campaign emails, which is where the human responses will go to.
The documentation on how to set this up is pretty straightforward.
https://docs.suitecrm.com/admin/administration-panel/emails/email/#_bounce_handling_account
In your campaign setup you want to set your bounce handling account.
You can monitor the status of your campaign and the bounced emails from the Campaign Status page. You can see how many emails were sent, opened, clicked, bounced, or unsubscribed. You can also see the details of each bounced email, such as the reason for bouncing and the date and time of bouncing. You can also manually mark an email address as invalid or opt-out if you want to exclude it from future campaigns. Or you can simply add all bounces to your unsubscribe list:
How Does SuiteCRM know an email has Bounced?
SuiteCRM knows an email is bounced when it receives a notification from the email server that the email could not be delivered. The notification usually contains a code and a message that indicate the reason for bouncing, such as a permanent failure (hard bounce) or a temporary failure (soft bounce). SuiteCRM parses these notifications and updates the status of the email address in the campaign accordingly. For example, if an email address is invalid or does not exist, SuiteCRM will mark it as invalid and to exclude it from future campaigns. If an email address is temporarily unavailable or has a full mailbox, SuiteCRM will mark it as bounced and retry sending the email later.
SuiteCRM knows an email has bounced when it receives a notification from the email server that the email could not be delivered. The notification is usually an email message that is sent to the bounce account that was specified in the campaign settings. The notification email contains a code and a message that indicate the reason for bouncing, such as a permanent failure (hard bounce) or a temporary failure (soft bounce).
Specifically, the checkBouncedEmailInvalid function is designed to return true if the email description (which includes the body, header and parsed attachements) contains a permanent error status (5.X.X) and an SMTP error 550. The regular expression and logic in the function seem correct for this purpose, and it should return true if the email description matches these criteria.
The regular expression checks for lines in the email description that start with “Status:,” followed by a sequence of three numbers separated by periods. If it finds a line with a permanent error status (5.X.X) and a line that contains “Diagnostic-Code: smtp; 550,” it returns true to indicate that the email is invalid due to a “550” SMTP error.
In which case it marks the activity_type as “invalid email” otherwise it marks it as “send error”. Most emails will get marked as “send error” because the criteria is very strict to mark invalid.
SuiteCRM then creates a log file and either shows it as bounced – invalid or bounced -other in the campaign.
NOTE: SuiteCRM only checks for bounce if the message is from “MAILER-DAEMON” OR “POSTMASTER”, otherwise it will be ignored. If you are using Sendgrid, Mailgun, Amazon AWS or any other third party bulk email delivery, you’ll have to edit the code accordingly. In /modules/Campaigns/ProcessBouncedEmails.php function campaign_process_bounced_emails()
How Does SuiteCRM Know which Campaign the Bounced email Pertains to?
SuiteCRM knows which campaign the bounced email pertains to by using the bounce handling account that was specified in the campaign settings. The bounce handling account is a special email account that receives the notifications of bounced emails from the email servers. SuiteCRM parses these notifications and matches them with the campaign emails that were sent. For example, if the campaign email had a header like this:
From: auto-mail@example.com
To: john.doe@invalid.com
Subject: Join our newsletter and get 10% off
X-Campaign-Id: 1234567890Then SuiteCRM will look for the X-Campaign-Id header in the notification email that is sent to the bounce handling account. If it finds a match, it will update the status of the campaign and the email address accordingly. You can see the details of each bounced email from the Campaign Status page.
What Happens if the Server Responds with an Attachment of the email Instead?
SuiteCRM can still know which campaign the bounced email pertains to even if the original email is an attachment. This is because the original email contains a header called X-Campaign-Id, which is a unique identifier for the campaign. SuiteCRM parses the attachment and looks for this header to match it with the campaign. This way, SuiteCRM can update the status of the campaign and the email address accordingly.
What if You Are Sending Through a Bulk Email Sender?
If you are sending through Sendgrid or Mailgun or Amazon SES or similar service, they generally set their own return bounce path. So you’ll have to check with your provider. For example in Sendgrid you can select a bounce mailbox for this purpose (use your SuiteCRM bounce email address)
Also, bounced emails will come from no-reply@sendgrid.net. This would have to be added to: /modules/Campaigns/ProcessBouncedEmails.php function campaign_process_bounced_emails()
for example:
if (preg_match('/MAILER-DAEMON|POSTMASTER|no-reply@sendgrid\.net/i', $emailFromAddress)) {
// Your code to handle bounce emails from MAILER-DAEMON, POSTMASTER, or no-reply@sendgrid.net
}Amazon emails come from: MAILER-DAEMON@amazonses.com so they will be matched.
How Are “out of office” replies handled?
Out of office replies are not retuned to the “bounce” account. Out of office replies are generally returned to the “reply to” and they are not generally sent by MAILER-DAEMON or POSTMASTER to the bounce path. So they do not count as bounces.
When does bounced emails run and how?
You would think it runs with the scheduled job “Run Nightly Process Bounced Campaign Emails”, but it does not. It does not run when “Check Inbound Mailboxes” job runs.
Run Nightly Process Bounced Campaign Emails essentially just does the same thing as “Check Inbound Mailboxes” except that it is limited to the bounce account.
So you must make sure at least one of these jobs is running in the Scheduler and your cron jobs is triggering them.
Are Bounced Emails Marked as Invalid?
It depends… If an email meets the criteria of “Invalid” then they get marked as “invalid email”, in which case it will not only log in the campaign as and invalid email, it will mark the record email as invalid.
However, if the email bounces and does not meet the criteria of “invalid” it gets marked as “send error”. In which case it does not automatically mark the email as invalid. You have a few choices at this point. You may just want to add send error bounces to your unsubscribe list. Or, for the most part they will probably really be “invalid” because the criteria is so strict for what counts as invalid. Unfortunately, you can’t create a workflow to do this for you and mark these email addresses in the contact/lead records as invalid because the “invalid” field is not available to update by workflow in the lead/contact record.
However, you could add these to your unsubscribe list, or create a special unsubscribe list like “Invalid Emails”. You could create a scheduled job in scheduler to look through the Invalid Emails target list and mark them as invalid by leveraging the functionality already in bounced emails functionality.
How does this affect email validation?
You definitely do not want to keep bouncing emails to the same contact. This can affect your spam rating with the receiving server and if you’re using a bulk emailer like Sendgrid or AWS you don’t want to have a high bounce rate or they may lock your sending ability. So, it’s good practise to know how your bounce management system works and to either unsubscribe or mark bounced emails as invalid so you don’t continue to send to them.
Still Need Help?
Please reach out to me! I help people with SuiteCRM for a living. Coaching, training, customization and development, I do it all. Contact me if you need help.