////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////

==== SMTP Server Configuration

By default, the plugin assumes an unsecured mail server configured on port 25, getting the SMTP host name from the environment variable `SMTP_HOST`. However, you can change this via the `grails-app/conf/application.groovy` file.

Here is an example of how you would configure the default sender to send with a Gmail account:

[source,groovy]
----
grails {
    mail {
        host = 'smtp.gmail.com'
        port = 465
        username = 'youraccount@gmail.com'
        password = 'yourpassword'
        props = [
            'mail.smtp.auth'                  : 'true',
            'mail.smtp.socketFactory.port'    : '465',
            'mail.smtp.socketFactory.class'   : 'javax.net.ssl.SSLSocketFactory',
            'mail.smtp.socketFactory.fallback': 'false'
        ]
    }
}
----

And the configuration for sending via a Hotmail/Live account:

[source,groovy]
----
grails {
    mail {
        host = 'smtp.live.com'
        port = 587
        username = 'youraccount@live.com'
        password = 'yourpassword'
        props = [
            'mail.smtp.starttls.enable': 'true',
            'mail.smtp.port'           : '587'
        ]
    }
}
----

If your mail session is provided via JNDI, you can use the `jndiName` setting:

[source,groovy]
----
grails.mail.jndiName = 'myMailSession'
----

==== Configuration Defaults

You can set various _default_ settings via the application configuration that will be used in the absence of explicit values when sending email.

You can set the default "from" address to use for messages in `application.groovy` using:

[source,groovy]
----
grails.mail.default.from = 'server@yourhost.com'
----

You can also set the default "to" address to use for messages in `application.groovy` using:

[source,groovy]
----
grails.mail.default.to = 'user@yourhost.com'
----

==== Disabling Email Sending

You can completely disable the sending of email by setting:

[source,groovy]
----
grails.mail.disabled = true
----

You may want to set this value for the development and/or test environments. However, this will treat any call to `mailService.sendMail()` as a no-op, which means that the mail plugin will not attempt to render the email message or assemble any attachments. This can hide issues such as incorrect view names, or invalid or non-existent configuration, during development.

==== Overriding Addresses

An alternative to disabling email is to use the `overrideAddress` config setting for your development and/or test environment to force all email to be delivered to a specific address, regardless of what the addresses were at send time:

[source,groovy]
----
grails.mail.overrideAddress = 'test@address.com'
----
