Skip to main content
Skip table of contents

Mail Server Connection

An instance of Connection is the first parameter of all MailClient operations. On first encounter in a call, the library will initiate the connection and retain it, i.e. successive calls using the same connection settings will re-use the already opened connection to the mail server, where "same" is identified by host+user+protocol+port+security. So changes to any of these attributes will be considered being a "new" connection, while changes on any other attributes have no effect.

Migration Information

Attributes keystore and keystorePassword that you may miss if you are migrating from version 1, have been removed from the Connection object. Loading the keystore is now a global operation on the Crypto class, see Keys and Certificates.

Connection

Class Connection has the following attributes:

Attribute NameTypeDescriptionAllowed Values
debugBooleanSpecify whether to write additional debug information to the bridgeserver log.trueAdditional debug information is written to the bridgeserver log.
falseNo additional logs (default).
exchangeVersionStringSpecify the Microsoft Exchange version (optional).2007_SP1 Exchange 2007 Service Pack 1
2010Exchange 2010
2010_SP1Exchange 2010 Service Pack 1
2010_SP2Exchange 2010 Service Pack 2 and higher (default)
hostStringSpecify the host name/IP address of the mail server.a valid host name or IP address

for exchange connections this can be left NULL, triggering Autodiscover (which might fail)

for  office365 connections this is ignored

microsoftOnlineCredentialsObjectSpecify OAuth login credentials for Microsoft Online connectionsa valid set of credentialseither this or usernamePasswordCredentials must be set
portIntegerSpecify the port of the mail server (optional)a valid port numberIf omitted (NULL), the standard port for the chosen protocol and security is used.
protocolString

Specify the protocol used for e-mail retrieval and storage.
Values are not case sensitive.

imapUse the IMAP protocol.
imapsUse IMAP over SSL.
pop3Use POP3.
smtpUse the SMTP protocol.
smtpsUse the SMTPS protocol.
exchangeUse Exchange Web Service (EWS) API with a hosted Exchange Server
office365Use Exchange Web Service (EWS) API with a Office 365 Server (will ignore host).
securityString

Specify the encryption.
Values are not case sensitive.

exchange and office365 protocols ignore this setting and use ssl anyway.

noneNo encryption used.
exchange and office365 protocol (see attribute protocol) use SSL in any case, this cannot be overridden.
ssl

Use SSL encryption. 

starttls

Use TLS encryption.
exchange and office365 protocol (see attribute protocol) use SSL in any case, this cannot be overridden.

Make sure to pick imap, pop3, or smtp with this setting, not imaps, pop3s, or smtps.

timeoutSecondsIntegerSpecify the number of seconds after which a request (send or receive) times out.

any positive integer

Default is 0, which translates to the following defaults:

  • infinite timeout for imap(s), pop3(s), and smtp(s)
  • 100 seconds for exchange
usernamePasswordCredentialsObjectSpecify the user's credentialsa valid set of credentialseither this or microsoftOnlineCredentials must be set
verifyHostBooleanSpecify whether for SSL connections the mail server host shall be verified or not (optional).trueVerify the mail server's SSL certificate (default, see also security).
falseDo not verify the mail server.
Username and Password Credentials
usernamePasswordCredentials.username
StringSpecify the user account on the mail server.a valid user name
Some SMTP servers allow unauthorized sending, in these cases you may leave it as NULL.
usernamePasswordCredentials.password
StringSpecify the user's password.a valid password
Some SMTP servers allow unauthorized sending, in these cases you may leave it as NULL.
Microsoft Online Credentials (only applicable to office365 protocol)
microsoftOnlineCredentials.clientId
Stringclient id of your app registration


For details on registering EWS access via OAuth please follow the steps as outlined here: https://docs.microsoft.com/en-us/exchange/client-developer/exchange-web-services/how-to-authenticate-an-ews-application-by-using-oauth

Make sure to follow the path for "app-only authentication"

microsoftOnlineCredentials.clientSecret
Stringclient secret of your app registration
microsoftOnlineCredentials.tenantId
Stringtenant id of your microsoft online organization
microsoftOnlineCredentials.impersonatedUser
Stringname (email address) of the mailbox you want to impersonatea valid email address
Provide the email address of the mailbox you want to interact with (e.g. read messages from)

Proxy Settings (only applicable to HTTP based connections, i.e. exchange or office365 protocol)

proxy.hostStringSpecify the host name/IP address of the proxy server.a valid host name or IP address
proxy.portIntegerSpecify the port of the proxy server.a valid port number
proxy.domainStringSpecify the user domain on the proxy server (optional). Some Windows-based proxy servers might require this for authentication.a valid ActiveDirectory domain name
proxy.userStringSpecify the user account on the proxy server (optional).a valid user
proxy.passwordStringSpecify the user's password (optional).a valid password

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.