Internet mail address updates

This topic describes how Traveler handles internet mail address updates in Domino Person documents.

Where is the internet address stored in Traveler?

Traveler Database: DEVICES table

When a device first registers with Traveler, a device table record is created. One of the fields within this a record is EMAIL_INTERNET. Traveler stores the value returned from the user’s person record in the directory. This information is for informational purposes to return on the Traveler Admin API Devices or Devices/Security queries. For more information, see HCL Traveler Administration API.

User Cache

The Traveler server keeps an in-memory cache of user information for active users (active=one or more devices accessing the server within a period (normally 24 hours) to avoid repeatedly having to look up the same information). This information includes name information, mail servers, and ACLs including a user’s email addresses. This information is populated the first time a device connects to a particular server after a restart or being load balanced. For more information, see Name lookup.

Address Cache

Mobile device clients generally do not understand Domino format for mail addresses (for more information, see Address conversion). Therefore, Traveler substitutes an internet address for a Domino name before syncing to a device or vice versa when a device is sending a mail. This lookup information/mapping is stored in this in-memory cache to avoid repeatedly looking up the same user address information and is populated the first time the address is needed to sync a data item to/from a device. For more information, see Name lookup.

What triggers an email address update?

Updating the User Cache

When the user cache entry is cleared or otherwise rebuilt (expires), Traveler checks if the internet address has changed and, if so, updates any record in the database where the internet address is stored such as EMAIL_INTERNET in the DEVICES table. A user cache entry is loaded from the directory lookup under the following conditions:
  • User not already present in the cache. This could be because the server has been recently restarted, the entry has been deleted (due to expiration), or the user has been load balanced to another server. There are several notes.ini’s that govern the behaviour of this cache. NTS_USERCACHE_LIFETIME indicates the lifespan of a cache entry (default of 4 hours). NTS_USERCACHE_EXPINTERVAL specifies how often to kick off a thread to scrub the cache of expired entries (default of 30 minutes). The act of purging an entry of the cache does not trigger a new lookup. That is driven by the next device request.
  • Console command: tell traveler clearcache user <user name>. This clears the user cache entry for the specified user. A value of * indicates ALL user cache entries.
  • Console command: tell traveler user <user name> or tell traveler dump <user name>. Both commands begin a new directory query and update the cache entry with the latest results.

See Notes.ini settings for all information on the notes.ini’s for the user cache. Traveler tracks user cache usage with statistics Traveler.UserCache.*.

Updating the Address Cache

An address cache entry is loaded during the address substitution process under the following conditions:
  • Address mapping not in the cache. This could be because the server has been recently restarted or the entry has been deleted (due to expiration). The lifespan of an entry is governed by the notes.ini setting NTS_ADDRESSCACHE_LIFETIME (default 24 hours). How often Traveler checks for expired entries (to delete them) is determined with the setting NTS_ADDRESSCACHE_EXPINTERVAL (default 30 minutes). In addition, there is a 30,000 entry limit (NTS_ADDRESSCACHE_MAX_ENTRIES) for the cache such that if that limit is reached, older entries are deleted.
  • Console command: tell traveler clearcache address. This drops the entire cache and does not have a “by user” deletion option because the cache is for the address, which could be in any document that any user is syncing (such as an email CC’ed to the user or a calendar event with the user as an attendee) and not necessarily just documents syncing to the user who is associated/owns the internet address.

Traveler keeps statistics on the address cache usage (Traveler.AddressCache.*)

What triggers an account username update on a mobile client?

The user name or account field associated with the server login is often the user’s internet mail address, but the field does not necessarily have to be the internet address and is treated as a separate entity from the internet address. This field is not updated.

What triggers an internet email update on a mobile client?

Some devices show the internet address, but others do not.

Verse Android

For Verse Android, the internet address is not displayed, so there is nothing to visually update. The address list is updated periodically. When the server detects an address change for a Verse Client, it will notify the client via push notification (FCM) that a get config is needed to pick up a settings change (address list).

Verse iOS

For Verse iOS, the internet address is displayed in Settings but there is no manual or automatic process for updating the internet address once it is configured with a valid internet address (Verse only updates the address if the previous address was invalid). The address list is updated periodically. When the server detects an address change for a Verse Client, it notifies the client via push notification (APNS) that a get config is needed to pick up a settings change (address list).

Apple Mail (iOS) client

For the Apple Mail app, the internet address is displayed in the account information. The internet address is also considered as the full address list (a list of only one). The Traveler server does signal that a settings command is needed on a push response when the change in address is detected (corresponds to the user case entry being updated). The app queries the Traveler server via the Microsoft Exchange ActiveSync Settings command that includes the UserInformation tag in the request payload. The Traveler server response includes the SmtpAddress pulled from the Traveler user cache. The Settings command is typically done at startup or after a period of time. From experience, rebooting the device tends to be the best way to force the Settings command to be issued. When the Settings response includes the updated internet address, we have seen that the account may still show the older internet address until the device is rebooted. Therefore, a device reboot is the best way to get the updated internet address and have it displayed in the account settings.

What are the effects of the email address being outdated?

Devices record

The email address in the devices record is for information only. It is not used in mail/device processing within Traveler. However, if there are admin tools using the Devices API, there could be impacts if the information is wrong.

User Cache

All of the devices use the internet address as part of a list of addresses for identifying the user (for example, to remove yourself from Reply All). For the Verse Clients, the user’s email address is passed to the client on a getConfig request in the devpmailaddresslist, which contains all forms of addresses that the Person document in the Domino Directory contains. The first entry is the canonical address and the last in the list is the preferred internet address. The Verse Android client uses the preferred internet address as the BCC user if the user has set “always bcc myself”. All of the clients use the internet address as the From address. However, it is important to know that Traveler ignores what the clients supply as the From address and always uses the authenticated identity to determine the sender’s Domino name. This prevents potential spoofing by a malicious client.

Address Cache

If an address is old in the cache, then when syncing a mail to the client, the server may substitute the old email address for someone in the address list (to/from/cc/bcc). At this point, the data is considered “Synchronized data”.

Synchronized data

Once mail is synchronized to the device with old addresses in the to/from/cc/bcc list (no matter if it is one minute ago, or one year ago), the only method to update those mails is a full resync.

Sending mail

When the client is sending a mail (either new mail or a reply), the address substitution is reversed. Any address that cannot be found in the cache or via lookup is left as-is which may cause a delivery failure if the old internet address is no longer deliverable.

Recent Contacts

The Apple Mail app keeps a list of “recent contacts” that is provided when trying to address a mail. If a recent contact has been updated/renamed, there is no automatic process to refresh these. The end user must manually remove these contacts, as they are now incorrect.