How to set up OS X Server Mail to auto-configure Mac Mail IMAP clients?
I did a little digging and found out a little of what OSX tries to do to auto-configure an email account.

In system preferences when adding a mail account, OSX makes a POST to https://mac-services.apple.com/iconfig/dconf the post parameters are:

domain: EMAIL_DOMAIN_THE_USER_ENTERED.com
version: 1
capabilities: MACOSX


For a service like gmail the following is returned:

&lt;domain&gt;
  &lt;name&gt;gmail.com&lt;/name&gt;
  &lt;description&gt;Gmail&lt;/description&gt;
  &lt;service&gt;
    &lt;hostname&gt;imap.gmail.com&lt;/hostname&gt;
    &lt;port&gt;993&lt;/port&gt;
    &lt;protocol&gt;IMAP&lt;/protocol&gt;
    &lt;ssl/&gt;
    &lt;requires&gt;MACOSX&lt;/requires&gt;
    &lt;authentication&gt;PLAIN&lt;/authentication&gt;
  &lt;/service&gt;
  &lt;service&gt;
    &lt;hostname&gt;smtp.gmail.com&lt;/hostname&gt;
    &lt;port&gt;587&lt;/port&gt;
    &lt;protocol&gt;SMTP&lt;/protocol&gt;
    &lt;ssl/&gt;
    &lt;requires&gt;MACOSX&lt;/requires&gt;
    &lt;authentication&gt;PLAIN&lt;/authentication&gt;
    &lt;usernameIncludesDomain/&gt;
  &lt;/service&gt;
&lt;/domain&gt;


Unfortunately, for my domain I receive the following response:

&lt;domain&gt;
  &lt;name&gt;EMAIL_DOMAIN_THE_USER_ENTERED.com&lt;/name&gt;
  &lt;unknown/&gt;
&lt;/domain&gt;


As far as I can tell after an unknown response OSX gives up and requires a user to enter the details manually. Capturing network packets I see no attempt by OSX to fallback to using SRV DNS records, or the Exchange Autodiscover.xml mechanism.

If I get a chance I will open a support ticket with apple to see how one gets added to their mac-services list.