ADAM

Communication Settings in ADAM

Introduction

In order to send emails from ADAM’s Messaging Centre, and to receive automated notifications from ADAM, it will be necessary to link ADAM up to an SMTP service provider through which it can send emails.

Navigate to Administration → Site Administration → Edit Site Settings. On the Communications tab, scroll down to the Email Settings section.

The Email Return Name and Email “From” Address fields are used only when ADAM sends an automated notification email - in other words, an email that wasn’t sent by a person.

Where a user sends a message from the Messaging Centre, ADAM will use their name as the “Return Name” and their email address and the “From Address”. This ensures that any replies to that person’s email are directed to them and not to another person who may not understand the reason for the reply.

The SMTP Server for Outgoing Mail and the SMTP Server Port for Outgoing Mail need to be specified and your network support personnel are best positioned to tell you what details go here. This includes whether the connection is SSL protected, and the SMTP Username  and SMTP Password.

The SMTP Session Limit tells ADAM how many emails its allowed to send once it has logged on to the server. Some servers have low limits, and others have higher limits. Again, your network support personnel are the best people to ask. If in doubt, leave this at 50. It can always be changed later.

The Sending Mode is important. The ideal scenario is to Deliver from “sending user”. However, this requires that the SMTP Username is permitted to send email on behalf of other users. This isn’t always allowed by email service providers.

A good option as a second choice, but one which is not permitted by many email servers is option 2: deliver from “sending user” with the return path as the “from” address.

Depending on how your email server is configured, if it doesn’t allow the SMTP Username to deliver on behalf of other users, you may have to rely on a “reply-to” address for the sending user. The safest option is likely “5”, but this looks least professional on the receiving end.

If you’re in doubt, experiment with these in order from 1 to 5 to see which works for your network.

Testing Mail Sending

To test these sending settings, you can navigate to Administration → Messaging Administration → Send test emails.

Enter your own email address in the Deliver To field and click on the Send button. Note that changing the “From” option allows you to test the difference between an automated email (from ADAM) vs a message sent by a person from the Messaging Centre (“from You”).

When you click on the Send button, ADAM will immediately send you an email. Check your email inbox.

If you get an error message reported, you may need to check the error logs to see what problem ADAM encountered.

Checking the Error Logs

Navigate to Administration → Debugging and Error Logging → View error log.

In the log, within the first few rows, you may see one or more “Warnings” that are associated with the page “classes/ADAM/EmailMessage”:

On the right-hand side (you may need to scroll across, horizontally to see it), you should see an error message (in the diagram below, we’ve covered up some confidential information!):

Be sure to pass this error message on to your network support personnel for them to assist in resolving the issue.

Understanding What Else Could Go Wrong

If you sent the message and received a success notification, it means that ADAM successfully handed the email over to the SMTP server. In this instance, you won’t see any error messages in the error log. However, lots can still go wrong. The problem is that none of this is in ADAM’s hands any more. Like a letter in the mail, we can ensure the address is correct and that we have the correct stamps in place, but from the moment you put it in a postbox, you no longer have any control over its delivery.

If you don’t receive the email from ADAM, you can check your junk mail or spam folder to see if it’s there. If not, you’ll have to get further help from your network support personnel who can investigate further.

Have a look at our section on the Messaging Centre and Spam mail.

Sending email from ADAM if you use Google Workspace

If you are a “Google School” that makes use of Google’s email offering, then the preferred method of mail delivery, to reduce the possibility that emails sent from your ADAM server will be interpreted by the recipients as spam mail.

Configure Google Workspace

Follow the official instructions to configure the SMTP relay service in Google Workspace’s Admin Console.

However, please take note of the following points:

Please also set up a user that can be used to authenticate to the service. For example: adammail@example-school.co.za with a 20 random-character password. Please be careful that this user is not subject to any synchronisation services, password expiration policies or such. If this account is disabled or if its password changes, ADAM will no longer be able to send mail.

Configure ADAM

Navigate to the ADAM Site Settings: Administrator → Site Administration → Edit site settings.

On the Communications tab, scroll down to Email Settings. Update the following settings as indicated:

If you see that any of these settings are “Set in the configuration file” and your ADAM server is hosted on our cloud platform, please contact ADAM Support so that we can assist you in changing these settings! If you host your own ADAM server, please see elsewhere in this documentation for assistance editing the configuration file.

Once finished, save the settings. Navigate to Administration → Messaging Administration → Send test emails. From here, send yourself an email and check that:

  1. ADAM reports a success; and
  2. the email arrives in your inbox.

If you can tick off both of those, then your mail is set up correctly.

Sending email from ADAM if you use Microsoft’s O365

Firstly, a disclaimer: we have noticed that mail delivery via O365 is not perfect and Microsoft itself can block your server from delivering messages to it if it considers those messages to be spam-like. ADAM has no control over the email that you send (i.e. its content, frequency and user-friendliness) and has no control over how Microsoft chooses to interpret that email. Your experience may vary!

Configuring O365

Follow the instructions on Office 365’s official help site for Option 3. Note that while Microsoft recommends Option 1, both Options 1 and 2 are not compatible with how ADAM sends email. Both of these options will re-write the sender header meaning that recipients of the email will reply to a single central email address and the sender will not get those replies delivered to them.

The document, at the time of writing, states the following for Option 3:

Only choose this option when:

SMTP client submission (Option 1) is not compatible with your business needs or with your device

You can't use direct send (Option 2) because you must send email to external recipients.

In this case, Option 1 fails the “business needs” criterion: email replies must be directed to their sender, and Option 2 doesn’t apply because you need to send emails to external recipients - i.e. parents.

You will need to know the IP address of your ADAM server. If you make use of a hosted ADAM server, please inform us so that we can give you the IP address of the server.

Please take note of Step 3 in the instructions. You will need this “POINTS TO” address when configuring ADAM. In Step 8 of the instructions, make special note of the configuration of your SPF record.

Configuring ADAM

Navigate to the ADAM Site Settings: Administrator → Site Administration → Edit site settings.

On the Communications tab, scroll down to Email Settings. Update the following settings as indicated:

Alternative Configuration for Microsoft’s O365

Kindly note that these are theoretical settings that have not been tested. They may be more reliable than the method discussed above, but have much more stringent controls with regards to the volume of messages that can be sent. Try this at your own risk and make sure to monitor the messaging centre batches for failure notifications.

This method makes use of a single address to send email from ADAM. We recommend creating a single user in your O365 control panel for this purpose. The user should be sufficiently generic (e.g. “Example School’s ADAM”. The user should have a strong password associated with it.

Configuring Office 365 - Alternative Method

Follow the instructions on Office 365’s official help site for Option 1.

Configuring ADAM - O365 Alternative Method

Navigate to the ADAM Site Settings: Administrator → Site Administration → Edit site settings.

On the Communications tab, scroll down to Email Settings. Update the following settings as indicated:

Troubleshooting Email Delivery Issues in ADAM

Have a look at our section on the Messaging Centre and Spam mail.

ADAM does not deliver mail directly to the recipients. It requires an intermediate server to take over the delivery of the mail. This is done for a number of reasons:

  1. ADAM delivers emails one at a time, in the order that the emails were loaded.
  2. ADAM is designed to “fail easily” when sending messages.
  3. There are many complexities with sending email that are better left to specialist software.

ADAM processes email in a queue, and sends messages one at a time. This means that delivery is slow. By using an intermediate server, the messages can be handed off to that server quickly since it has only one computer to talk to (which is normally on the same LAN or even same computer as ADAM). This software can then deliver email more efficiently to recipients by delivering mail in parallel and retrying the delivery of messages that couldn’t be sent on their first attempt.

Step 1: Did ADAM send the message?

The first thing for a site administrator to do is to check the messaging batch records. These can be found Administration → Messaging Administration → View Messaging Centre Batches.

Click on the view link to view the details of a batch.

Here, ADAM records whether an email was sent and, depending on the email program that the recipient is using, when the message was opened.

ADAM will list the time that the email message was processed if it was successful, or list the fact that there was an error at that time. If ADAM shows an Error, then the message was not sent.

If ADAM did not send the messages (there is an “Error” listed under “Processed”), then you will need to investigate:

  1. Which server is ADAM talking to (set in the Site Settings under the Communications tab, look for SMTP Server)?
  2. Is ADAM using the right authentication credentials to talk to the SMTP server?
  3. Is the SMTP server on and configured to listen to ADAM?

Advanced network administrators will want to check the logs of their SMTP server to see if there are clues there are to why the emails from ADAM are not being accepted for delivery.

Further information as to why ADAM didn’t succeed in delivery are shown in the ADAM Error Logs.

Step 2: Check your mail server for issues

From this point on, you will want to engage the services of an email server expert to determine why your email isn’t being delivered. Unfortunately, after the email is passed to the upstream SMTP server, the delivery of those emails are out of our control. To use an apt analogy: once you drop the letter into a postbox for delivery by the post office, you no longer have control over its delivery.

Step 3: One mail or an entire batch?

If you recieve a bounce notification for a single email - or perhaps each time a batch is sent, a familiar set of bounce notifications return, then you will need to check that those email addresses are captured correctly. It may be that an email address no longer exists, that the mailbox is full or a host of other reasons. These are all out of our (and your!) control.

Very often, a telephone call to the recipient is best to determine whether there is an alternative email address that you can use instead.