examples/imap-autoconf/README.adoc

= Auto-configuration of Mail User Agents

== RFC-6186 use of SRV records

link:https://tools.ietf.org/html/rfc6186[RFC-6186] defines the usage of SRV records in order
to help users configuring their Mail User Agents in order to access your service, as it allows
to locate your services (hostnames and ports).

You would then need to publish SRV records on your DNS.

----
_imaps._tcp.domain.tld. 3600       IN    SRV    0 1 993 imap.domain.tld.
_submission._tcp.domain.tld. 3600  IN    SRV    0 1 587 smtp.domain.tld.
_jmap._tcp.domain.tld. 3600        IN    SRV    0 1 443 jmap.domain.tld.
----

== Thunderbird

Thunderbird relies on a custom XML payload being served on a subdomain.

For `user@domain.tld` an HTTP GET request would be done at `http://autoconfig.domain.tld/mail/config-v1.1.xml`

You could for instance serve the following XML payload:

[xml]
----
<clientConfig version="1.1">
  <emailProvider id="MessagingEngine">
    <domain>domain.tld</domain>
    <displayName>My company</displayName>
    <displayShortName>My company</displayShortName>
    <incomingServer type="imap">
      <hostname>imap.domain.tld</hostname>
      <port>993</port>
      <socketType>SSL</socketType>
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </incomingServer>
    <outgoingServer type="smtp">
      <hostname>smtp.domain.tld</hostname>
      <port>465</port>
      <socketType>SSL</socketType>
      <authentication>password-cleartext</authentication>
      <username>%EMAILADDRESS%</username>
    </outgoingServer>
  </emailProvider>
</clientConfig>
----

== JMAP

link:https://datatracker.ietf.org/doc/html/rfc8620[RFC-8620] defining JMAP core RFC defines precisely service location.

James already redirects `http://jmap.domain.tld/.well-known/jmap` to the JMAP session.

You can further help your clients by publishing extra SRV records (see above).

== Example

We ship a little example hereby to ease set up.

It is comprised of a docker-compose starting a James and a side container to serve Thunderbird auto-configuration.

 - 1. Start the docker-compose

----
docker-compose up
----

 - 2. Create `domain.tld` and a user `bob@domain.tld` with a strong password (`123456`)

----
docker exec -ti james james-cli AddDomain domain.tld
docker exec -ti james james-cli Adduser bob@domain.tld 123456
----

 - 3. Register the domains `autoconfig.domain.tld`, `imap.domain.tld` and `smtp.domain.tld` in your `/etc/hosts` file.

----
127.0.0.1       domain.tld imap.domain.tld smtp.domain.tld autoconfig.domain.tld
# ...
----

 - 4. Start Thunderbird and enjoy auto-configuration!

image:thunderbird_autoconf.png[Auto-configuration was applied in Thunderbird]