MailQuery Troubleshooting

mailQuery Event Email Created Without an Email Icon

An event email can be created without a corresponding Mail Queue record in the following circumstances:

• It was created from a mailQuery scheduler job

• The recipient_1_to_address in the query is blank

An email record cannot be created in this situation, because you can't resend a mailQuery email from an Event tab.

To fix this, check where the required email address comes from and update the source record (for example: Client contact, Driver, etc).

AWS SES Setup

Amazon Simple Email Service (SES) is our recommended emailing method. DomainKeys Identified Mail (DKIM) is the authentication method we use for SES. Each Domain Name that will send emails needs 4 domain keys listed against the Domain Name.

Warning: Once your SES keys are set up, they must remain in place. If these keys are removed, your emails will not send and drivers and employees will receive error messages in the Driver Portal.

Set-up Steps

1. Send an email to Catch-e Support listing the domains you want to use to email from Catch-e.

2. Catch-e Support will:

   • Raise a service request task

   • Check that any existing entries in the gb_mail_sender_domains table are listed

   • List all the required URLs on the task and assign to the System Administrator

   • Create the 4 entries (per domain) for the listed URLs and document the domain keys (DKIM) into the task. Assign to the Analyst

   • Email the client with the domain key (DKIM) details

3. When you receive a return email from us with the details of the domain key entries, enter or arrange for them to be added to your Domain Name records. There will be 4 DKIM entries per domain.

4. Let Catch-e Support know when the DKIM entries have been added to your domain.

5. Catch-e Support will:

   • Note the confirmation on the task and assign to the System Administrator

   • Check and confirm that the activation has been successful (can take up to 72 hours, but typically completed within 1 hour of client DNS change) and assign to the Analyst

   • Update the relevant controls to use SES

   • Run confirmation email tests to confirm the update

6. The set up can finish here.

   Before you finish, check to see if you have any processes that use the email return path to authenticate the origin of emails (for example: SMSGlobal for email to sms services).

7. If you are using any processes like this, you will need to nominate a sub-domain to use for the return path.

   This should be a sub-domain, and not your main domain name, so the configuration does not disrupt your organisations settings. For example: use ses.catch-e.com.au, not catch-e.com.au

8. Advise Catch-e Support of the sub-domain name you want to use.

9. Catch-e will:

   • Email you the entries that need to be added to your DNS

   • Add or forward these entries to your Domain Manager to update

10. Advise Catch-e Support when this has been done.

11. Catch-e will:

    • Configure and verify the sub-domain name in AWS

    • Email confirmation of this to you

Update Global Controls

Once the domain keys have been verified, Catch-e Support will activate the Amazon SES service by updating the controls below to use the values shown.

Setup / Reference Data > gb_controls

Run Test Emails

Catch-e Support will conduct the following tests:

1. Send a test email to yourself to confirm reception

2. Send a test email to "bounce@simulator.amazonses.com"

3. Check that the associated record has been updated to 'bounced'

4. Send a test email to "complaint@simulator.amazonses.com"

5. Check that the associated record has been updated to 'complaint'

Useful SQL

-- All 'enrolled' domains will need to have their DNS records updated. SELECT * FROM gb_mail_sender_domains; -- Returns all recipients for the nominated mail_batch_no and their respective status_flag. SELECT * FROM gb_mail_recipients WHERE mail_batch_no = 'nnnnnn' -- AND mail_item_no = 1 -- AND recipient_no = 1; -- Provides additional information for the nominated mail_batch_no and their respective delivery_status and delivery_status_message. SELECT * FROM gb_mail_recipient_statuses WHERE mail_batch_no = 'nnnnnn' -- AND mail_item_no = 1 -- AND recipient_no = 1; 

For more information, refer to AWS Documentation for verifying a DKIM domain identity with your DNS provider.

Domain Setup

Overview

If you have ever received an email claiming to be from your bank, PayPal, or a company you do business with, but it is really from someone else, then you have seen first hand how easy it is to create fraudulent email. Authentication helps legitimate senders prove that their email is not a forgery, and can help receiving servers like ISPs and corporate email servers control inbound spam.

If any of our clients send emails from Catch-e where there is no SPF Record, eventually our mail servers will be treated as spammers and get blacklisted. This means any emails you send from Catch-e may randomly not get delivered.

The first step to ensure reliability in the email service from Catch-e is by registering the domains you use when sending email and creating an SPF Record.

Creation of the SPF record on your domain is by far the best option, however if you are unable to arrange this we can set up a sender email address that uses the Catch-e domain (for example: noreply@catch-e.com.au or client@catch-e.com.au). This is not ideal for you, but it will avoid the spam problem.

The "Reply To" address will still contain your original email address. When recipients reply to the emails, they will return to your original addresses as they do now.

Warning: If your domain is not registered with Catch-e and an SPF Record has not been set up you will be unable to send email from the Catch-e application.

Note: If the fall_back email is used to send an email, you will not be able to see this in the email or the mail queue. The original email Sender and Address will be shown.

Status Checks

Continuous checks are run in the scheduler to ensure the SPF records for your domains are correct.

This job checks and verifies the status of SPF records of domains stored in the gb_mail_sender_domains table if the status_flag of the record is 'enrolled' or 'failed'. All other statuses are ignored.

If the verification fails then the field is changed to 'failed' and information on why it failed is added into the error_data field.

If the verification succeeds for a 'failed' record, the status_flag is updated to 'enrolled' and data in the error_data field is cleared.

If the mail_sender_enabled is set to 'yes' and the domain record is not 'enrolled', your emails will either not send, or use the fall_back email if you have one.

Email Pop-up Behaviour

When an email pop-up is shown:

• If your Domain is enrolled, the "From" address will display your stored sender email

• If your Domain is not enrolled and you have a fallback email, this will display in the "From" address and a "Reply To" address that displays your stored email will also be shown

Mail Queue Behaviour for Bulk Emails

When bulk emails are created, they will be stored in gb_mail at 'pending' status with the original sender's address recorded.

When the emails are sent by a user, the domain status is rechecked and the emails will be either:

• Sent without change

• Sent with the sender_address updated to noreply@catch-e.com.au

• Set to 'Failed' and the user alerted

Driver Portal Email Behaviour

When a driver submits a claim via the Portal, the email confirmation is not mentioned on screen, so a driver will not be aware if an SPF record failure has occurred.

The event email is still created, but the email is displayed as 'Failed' in the Mail Queue.

Client Set-up

1. Contact your Account Manager to register your Domain with Catch-e in the gb_mail_sender_domains table

2. Read through the SPF Setup page. Set up an SPF Record on your Domain

Catch-e Set-up

In order for the domain checking process to be active the mail_sender_enabled control must be set to 'yes'.

Below is the structure for gb_mail_sender_domains: