Contents
- 1 Introduction
- 2 Configuration
- 3 Requirements
- 4 Checking that the mail settings are correct
- 5 Troubleshooting
- 5.1 No such host is known
- 5.2 A connection attempt failed because the connected party did not properly respond
- 5.3 No connection could be made because the target machine actively refused it
- 5.4 BDAT command has been rejected by the server
- 5.5 Mails are marked as spam
- 5.6 A user attempted to send an email from a non-verified domain
If your WorkBook is hosted by WorkBook Software this page is mostly irrelevant. |
Introduction
Sending mails from WorkBook is a very common task, but before this works some configuration is required.
WorkBook can send a large variety of mails including Time registration reminders, overdue invoices, personal communication with suppliers, etc.
Configuration
Outgoing mails are sent from WorkBook using SMTP (Simple Mail Transfer Protocol). This allows WorkBook to communicate with most mail servers.
NOTE: In order to send mails from WorkBook, system variable 1148 must be enabled
Requirements
-
- Address to the mail servers SMTP port
- Find out if the SMTP port uses plain or explicit SSL/TLS for communication
- Anonymous authentication for relaying or a username and password combination*
- An email address used for sending out automatically generated emails
*These authentication methods are supported for username and password:
-
- LOGIN (Plain text)
- SASL LOGIN
- SASL PLAIN
- SASL CRAM-MD5
- SALS DIGEST-MD5SMTP Server
The following system variables are used to control which SMTP server is used by WorkBook for sending mails:
Id | Name | Description |
---|---|---|
262 | SMTP server name or IP number | This is the IP address or domain name used by the mail server for receiving SMTP communication for outbound mails |
641 | SMTP port number | This is the port used to receive SMTP communication, the default for plain communication is 25 and 587 for SSL/TLS |
642 | Use SSL for SMTP | If the SMTP server expects explicit SSL/TLS, this will most often be the case if port 587 is used |
643 | SMTP Username | The username required for authentication. Most often a mail server accepts the full email address as username, example: something@mydomain.tld |
644 | SMTP Password | The password required for authentication |
646 | Use SMTP Login | Whenever the username and password specified here should be send to the server. If this is disabled WorkBook will attempt to send the mail without authenticating |
Common Configurations
If your organization is using one of the following providers, these are the settings required.
By default none of these configurations will allow your users to send as themselves, and therefor its recommend you enable system variable: (760) Force the use of email address from Agent sender.
Id | Name | Office 365 | Google Apps |
---|---|---|---|
262 | SMTP server name or IP number | smtp.office365.com | smtp.gmail.com |
641 | SMTP port number | 587 | 587 |
642 | Use SSL for SMTP | True / Checked | True / Checked |
643 | SMTP Username | <username>@<domain>.<tld> | <username>@<domain>.<tld> |
644 | SMTP Password | <Password> | <Password> |
646 | Use SMTP Login | True / Checked | True / Checked |
Sources: Microsoft Office Support, Google Apps Help
Mail addresses used
WorkBook needs an email address for sending automatically generated emails. Some mails are sent without any user interaction like Time Registration Reminders.
This email address can also be used to send all outgoing mails (because some servers does not support sending on behalf of other users)
The email address is controlled by the following system variables:
Id | Name | Description |
---|---|---|
289 | “From” email address | This is the mail address that WorkBook uses when sending notifications and other automated emails, it is recommend that it matches the mail address of your SMTP Server.The mail address can also be used as a forced sender, so all mails send from your employees is send using this mail address, but with a “Reply To” field pointing to the employee email. |
290 | Agent default “From” name | This is the mail displayed in the mailbox every time an automated mail is send using the: “From” email address. |
760 | Force the use of email address from Agent sender | This system variables forces all outgoing mails to be send using the address from the system variable: “From” email address as stated in system variable 289. Check your mail servers configuration to see if this is required. By default, both Office 365, Google Apps and Exchange Server requires this setting to function. |
None | None | In a few rare cases the sender email for Agents are configured in the Agent Parameters. |
Domain Verification
To send emails from WorkBook,you must also verify your domains in WorkBook. In hosted WorkBooks, there is already a domain configured by default.
See the following guide on the subject.
Checking that the mail settings are correct
The easiest way to check that the new settings are correct and working, is by sending an new email using the mail dialog to yourself.
Troubleshooting
The troubleshooting steps below are only suggestions and may not be full solutions.
Most of the headlines are partial matches of the error message.
No such host is known
Check system variable: (262) SMTP server name or IP number, the server is unable to resolve the DNS name you entered.
You may try and diagnose your DNS name issue using mxtoolbox.
A connection attempt failed because the connected party did not properly respond
This indicates connection issues to the IP Address used by your mail server, please make sure the IP Address or DNS Name is correct.
No connection could be made because the target machine actively refused it
This error indicates that the SMTP Server address is correct, but we are unable to connect to the SMTP Port.
Common causes is, firewall, wrong port number, or the SMTP Service is stopped.
BDAT command has been rejected by the server
This tells you that the sender email address has not been granted access to send mails from your server. You can choose to grant access to the mail address in question, or you can force the sending of mails with a default sender.
If you mark the checkbox in setting 760 in your system variables, the sender of mails will be changed to the value stated in system variable 290.
Mails are marked as spam
There can be multiple reason for this, start by checking your SPF and DKIM configuration.
If these mails are for internal users, consider white listing the emails. (Office365)