Setting up the Plug-in to work with your Mail Server

So you have SMTPit Pro installed and you are ready to send email? Great!

The first thing you must do is give the plug-in the settings required to connect to your mail server. Where you enter these settings will depend on how your database is setup. Here are a few examples of where this might be:

Figure 1 Layout

Figure 2 Calculation

Figure 3 Configuration Dialog

The six settings you will need to know are as follows:

• Host
• Port
• Authentication Type
• Username
• Password
• SSL/TLS/STARTTLS (if applicable)

If you do not know these settings, this will be a problem. Here are some ways to find out what they are:

• Find the settings you use in another email client. Already have Apple Mail, Outlook, etc. setup? Look for the SMTP settings in the preferences of the application.
• Contact your mail server administrator. If you are going to send email through your Internet Service Provider’s (ISP) mail server, contact your ISP to find out the settings.

Let’s look in depth at the different settings you will need…

Host

The Host setting is the address of the mail server you want to send email through. Think of it like a street address. A street address tells you how to find a specific place. The same is true of the Host to the plug-in. The Host setting tells the plug-in how to find the mail server. The Host usually looks something like:

• mail.domain.com
• smtp.domain.com
• 10.0.0.1

As you can see, the Host setting usually looks something like the URL of a website, or it can also be just an IP address.

Port

The Port setting tells the plug-in what port number to connect to on the mail server. Think of this like an apartment number. A street address (aka Host setting) tells you how to find an apartment complex, but the apartment number (aka Port number) tells you exactly which unit you are looking for. So, the Host setting tells the plug-in how to find the mail server, but it can only use a specific port to talk to the mail server, so you must tell it exactly which port to use. By default, the port number is 25. With many servers requiring SSL connections, it is common you will be using port 465, 587, or some other number. We will talk more about that in the SSL section below.

Authentication Type

This is one of two settings that confuses many people. One reason is that many email clients have types of authentication that do not actually exist. Let me explain what I mean by this. When an email client connects to a mail server, the mail server will greet the mail client and tell it all the features it has. Included in the features it will list the different types of authentication it supports. This interaction looks something like:

Notice where it says:

This is the mail server listing the types of Authentication types it supports. This mail server supports CRAM-MD5, Login, and Plain types of authentication. These three are the most widely used and supported types of authentication the majority of mail servers support. Not all mail servers support all three, but at least one of the three should be available. Some mail clients will have a "Password" type of authentication as an option which is not a real type, and creates alot of confusion.

Thanks for the explanation, but how do I decide which one to use?

Right! So you have a couple options how to determine this. One, you can turn on the transcript option in the SMTPit_Send function, and look at the data returned from the plug-in (it will look similar to the interaction above). Just look for the part that looks similar to:

The other way to decide is to use trial and error. I would suggest starting with CRAM-MD5, then Login, and finally Plain. This is the order of how secure the three types are. Plain transmits the data in plain text, Login has some encryption, and CRAM-MD5 is the most secure. In other words, use CRAM-MD5 if available, then Login, and finally Plain if it is the only type available. If an authentication type is not supported, you will likely get an error from the mail server saying something like:

Note, there are many many different email servers out there and they all return different messages, so it is hard to say exactly what yours will say for a certain error.

Username

The Username setting is pretty cut and dry. Generally this will be your email address you use with the mail server. If your email address is "bob@example.com", this would be the username. This is not always the case, however. Some mail servers only want the username and not the full address. In this case it would simply be "bob". If you do not know which way your mail server requires, first try the full email address. If that does not work (and you know for a fact your password is correct), try just the username. Generally mail servers will not give a cut and dry error response to this, so it will probably fall under an error like:

This error could really be about either the username or password (or both!), so this is more of a guessing game. Just be certain you are not misspelling the username or password.

Password

Again, this is quite cut and dry also. Either your password is going to be correct or it is not. If it is incorrect you will probably get an error similar to:

As before, this error could mean either the username, password (or both!) are incorrect. So check both the username and password when you get an error like this.

If you are confident you are specifying the username and password correctly but still getting this error, contact your mail server administrator. They will be able to help you further as the mail server is what is giving the error, not the plug-in.

SSL/TLS/STARTTLS

Many mail servers require an SSL ( also known as TLS/STARTTLS) connection to the mail server, so you must turn this on in the plug-in if your mail server requires it. There are two different types of connections; AfterConnect and BeforeConnect.

• The AfterConnect type of SSL connection means the plug-in first makes a normal, unsecured connection to the mail server, and then an SSL connection is opened. Your username and password are only sent after the SSL connection is opened, so no sensitive information is sent on the initial unsecure connection.

• The BeforeConnect type means the initial connection the plug-in makes to the mail server is an SSL connection.

Both SSL types are fine to use and neither have an advantage over the other.

The other part of an SSL connection is using the correct port number, which we already talked about. The two different types of SSL connections can only be used with specific port numbers. In general these two port numbers will be 465 and 587. The following are the normal SSL type and port number combinations

If the SSL type and port number are incorrect, you are likely to get an error similar to these:

Connecting and Errors

After defining all your settings, you can use the Connect or Send function which will open a connection to the mail server. If the settings are correct, the plug-in will connect to the mail server, at which point the mail server will ask for Authentication details which are in the form of a username and password. If all your settings are correct you will get a result message similar to:

Host set to: ‘smtp.gmail.com’; Port set to 587.
Authentication set to: Login; Username: username@gmail.com; TLSType: AfterConnect
Connected to: smtp.gmail.com.

However, if one of your settings is wrong, you will get an error. For example:

How you determine what setting is incorrect depends on the error. Take for instance the above error. The first thing you will probably notice is it says "authentication failed". While this is important, another important piece of information is where it says "SMTP Server Error". This means you successfully connected to the mail server!!. Granted you did get an error, but this tells us you were connected to the mail server because the error message is coming directly from the mail server itself. Because we did get connected to the mail server, we are confident the Host, Port, and SSL type (if applicable) are correct.

To fix this error you will need to check your username and password. As before, if you are confident they are correct, you will need to contact the mail server administrator.

If you got an error such as:

Notice these errors do not say "SMTP Server Error", so you know the plug-in was unable to connect to the mail server, so the problem is with one or more of the following settings: Host, Port, or SSL type (if applicable). The Authentication can only happen if you connect to the mail server, so those settings do not matter at this point.

To fix one of these errors you will need to adjust the Host, Port, or SSL type (if applicable) settings.

Other Possibilities

The above situations and errors are the most common things you will see. Of course there are also less common problems you may or may never run into.

• If the plug-in successfully connects to the mail server, but you get a strange error from the mail server, the best thing to do is contact your mail server administrator. Since they are in control of the mail server and run it, they will be able to best help you.

  There is one error of this nature that is a little more common:

  ERROR: Send: SendRcptToCmd: SMTP Server Error: 5.7.1 Unable to relay

  There are many different variations of this, but if it says the word "Relay", then see this FAQ article.

• If the plug-in cannot connect to the mail server, it is possible the settings are correct but there is some other problem. This could include, but is not limited to:

  • Your mail server is currently offline (perhaps it is being restarted or is having maintenance done). You would just need to contact the mail server administrator to check this.
  • Something is blocking the port you are trying to connect to the mail server with. Either try a different port (if available) or see if you have an Anti-Virus or Firewall program that is blocking the port you are using.
  • On the Windows platform, "WINSOCK" or "ESocketException" errors generally mean the plug-in cannot connect to the mail server. This could be the settings are wrong or something is blocking the port. See this link for a common problem related to this.