Zoomed Image
USA
800 691 9120
UK
01225 704844

Email Configuration

xAssets Configuration Guide
Deployment and Administration

Email Configuration

This page explains how to configure xAssets to send email notifications. Email is used for alert notifications, scheduled report delivery, subscription-based notifications, and mail-merge operations within transformations.

Prerequisites

Before configuring email, ensure you have:

  • An SMTP server or relay service that the xAssets application server can reach over the network
  • The SMTP server hostname or IP address and port number
  • Authentication credentials if your SMTP server requires them
  • A "from" email address that your SMTP server will accept as a valid sender

SMTP Configuration

Email settings are configured through Special Options in the xAssets database. Navigate to Admin > Settings > Special Options to set these values.

Required Special Options

Special Option Description Example
MailServer The hostname or IP address of your SMTP server. This is the only required setting. smtp.office365.com
FromMailAddress The "from" address used on all outgoing emails. Defaults to alerts@xassets.com if not set. xassets-alerts@yourcompany.com

Optional Special Options

Special Option Description Example
MailPort The SMTP port number. If not set, the system uses the default SMTP port (25). Use 587 for TLS submission or 465 for implicit SSL. 587
SMTPSSL Set to 0 to disable SSL/TLS. Any other value (or not set) enables SSL/TLS. Most modern SMTP servers require SSL/TLS. 1
SMTPCredentials Controls authentication method: 1 = use a credential pack named "SMTP"; 2 = use the EmailUserName/EmailPassword Special Options. Leave blank for anonymous relay (no authentication). 1
EmailSubject Default subject line for notification emails when no specific subject is provided. Defaults to xAssets Asset Management Alerts. IT Asset Alerts

Authentication Methods

Set SMTPCredentials to 1 and create a credential pack named SMTP:

  1. Navigate to Admin > Settings > Credential Packs (or create the credential pack file in the CustomerDataPrivate folder).
  2. Create a new credential pack with the name SMTP.
  3. Set the Username to your SMTP account username.
  4. Set the Password to your SMTP account password.
  5. Optionally set the Domain field if your SMTP server requires domain-qualified authentication (e.g. for Exchange servers using Windows authentication). Leave blank or set to . if not needed.

Tip: Credential packs store passwords securely in the CustomerDataPrivate folder, which is not web-accessible. This is the recommended method for SMTP authentication.

Method 2: Special Options

Set SMTPCredentials to 2 and configure these additional Special Options:

Special Option Description
EmailUserName The SMTP username (required when using this method)
EmailPassword The SMTP password
EmailDomain The authentication domain (optional, for Exchange/Windows authentication)

Warning: Method 2 stores the password in the Special Options table in the database. While this is functional, Method 1 (credential packs) is more secure because the credentials are stored outside the database in an encrypted file.

No Authentication

If your SMTP server accepts relay connections from the application server without authentication (common for internal mail relays), leave the SMTPCredentials Special Option blank.

Email Templates

xAssets uses HTML email templates for notification emails. Templates are defined within transformations that use the mail-merge feature.

A transformation can send emails by:

  1. Running a query to produce a list of recipients and data fields.
  2. Merging the query results into an HTML template.
  3. Sending the merged email to each recipient via SMTP.

Templates support standard HTML formatting and can include embedded images. The transformation editor provides the template content as part of the transformation definition.

Subscriber Notifications

Users can subscribe to specific notification transformations through their user settings. When a notification transformation runs, it checks the UserSettings table for subscribers and sends only to users who have opted in.

To enable subscription-based notifications:

  1. Create a notification transformation with the merge type set to cdousersettings.
  2. Users subscribe via their personal settings (the Notifications section of their user options).
  3. Each user's email address is taken from their user record or their linked custodian record.

Email Delivery Methods

xAssets supports two email delivery methods, configured by the merge type in the transformation:

Method Merge Type Description
SMTP (CDO) cdo or cdousersettings Sends directly via SMTP. This is the standard method.
Mail Drop maildrop Writes email files to a folder on disk for pickup by an external mail system. Used in environments where the application server cannot send SMTP directly.

For mail drop delivery, the email files are written to a configured directory and must be picked up by a separate mail transport agent.

Testing Email

To verify your email configuration:

  1. Ensure all Special Options are set correctly.
  2. Create a simple test transformation that sends an email to your own address.
  3. Run the transformation manually from Admin > Batch.
  4. Check your inbox for the test email.
  5. If the email does not arrive, check the batch job log for error messages.

Troubleshooting Delivery Issues

Common Error Messages

Error Cause Solution
"The mail server IP Address registry setting is missing" The MailServer Special Option is not set Set the MailServer Special Option to your SMTP server hostname or IP address
"SMTP CDO Level 1 Error" General SMTP connection or authentication failure Check the SMTP server address, port, SSL setting, and credentials
"SMTP by email authentication cannot be used because the Special Option EmailUserName is blank" SMTPCredentials is set to 2 but EmailUserName is not configured Set the EmailUserName Special Option or switch to credential pack authentication (Method 1)

Troubleshooting Steps

  1. Verify network connectivity -- confirm the application server can reach the SMTP server on the configured port. Use telnet smtp.server.com 587 from the server's command prompt.
  2. Check SSL/TLS settings -- if your SMTP server requires TLS, ensure SMTPSSL is not set to 0. If it requires a specific TLS version, this may need to be configured at the .NET Framework level.
  3. Verify credentials -- test the SMTP username and password independently using a mail client or command-line SMTP tool.
  4. Check the "from" address -- some SMTP servers reject emails if the FromMailAddress does not match an authorised sender for the account.
  5. Review batch job logs -- email errors are logged in the batch job that executed the transformation. Navigate to Admin > Batch > Batch Jobs and check the error details.
  6. Check spam filters -- if emails are being sent but not received, check the recipient's spam or junk folder. Ensure your sending domain has appropriate SPF, DKIM, and DMARC records.