what is the purpose of the mail_host field of users table?

[boxyball]

I am trying to write a back end interface for multiple domain hosting by reading the users and identities tables.
I see how you use identities table to record each user.
What drives the mail_host field?  Or is it just static based on the default_host field in config.inc.php?
Per the instructions below, why does roundcube care what the hostname of the server is?
It's DNS that sends email to a server's IP regardless of the server's hostname.

// WARNING: After hostname change update of mail_host column in users table is
//          required to match old user data records with the new host.

[SKaero]

One Roundcube install can work with different mail server so you could connect a local mail server as well as gmail. If your only connecting to one mail server then it should match what is in the default_host in the config.inc.php.

[boxyball]

I am still not understanding. 
The server I am setting up will host multiple different domains for email, yet the users table is only going to have the hostname of the server for all users?  For example, it will have
[email protected] and
[email protected]
resulting in two entries in the users table but since the server hostname is example1.com, user2 will also have example1.com in the mail_host field.  It would help to know what roundcube is using this field for.

[JohnDoh]

the mail_host field is used to make entries in the users table unique.

Say your username for logging into your imap server is "fred" thats not very unique. But there can only be 1 username of "fred" on a single server so if you sort it with the mail_host then its unique.
Because Roundcube can be used to connect to any number of imap servers on a single installation then there could be a user called "fred" on imap.server1.com and another totally different one on "imap.server2.com".

You have an exmaple of [email protected] but not all setups use the full email address as the username. some just use the user part.

[boxyball]

So is this a field that I manually change in the user table if I want roundcube to retrieve email from a different server?

[JohnDoh]

no. it its set by roundcube when the user is created, and used later to identify existing users. the actual value comes from your Roundcube config.