3 Sending Email - Reference Documentation
Authors: Grails Plugin Collective
Version: 1.0.8-SNAPSHOT
3 Sending Email
Mail is sent using thesendMail()
method of the mailService
. This plugin also adds a shortcut sendMail()
method to all controllers and services in your application that simply delegates to the mailService
. There is no difference between the two methods so the choice is stylistic.class PersonController { def create = { // create user sendMail { from "admin@mysystem.com" subject "New user" text "A new user has been created" } } }
sendMail()
method takes a single Closure
argument that uses a DSL to configure the message to be sent. This section describes the aspects of the DSL.class PersonController { def mailService def create = { // create user mailService.sendMail { from "admin@mysystem.com" subject "New user" text "A new user has been created" } } }
3.1 Sender And Recipient
Recipients
The DSL providesto
, cc
and bcc
methods that allow you to set one or more address values for these recipient types.sendMail { to "someone@org.com" cc "manager@org.com" bcc "employee1@org.com", "employee2@org.com" … }
"user@host.domain"
or "Personal Name <user@host.domain>"
.You can supply multiple values for to
, cc
and bcc
.sendMail { to "someone@org.com", "someone.else@org.com" … }
to
when sending an email, the default to address will be used.
If the configuration property grails.mail.overrideAddress
is set, each recipient address specified will be substituted with the override address. See the configuration section for more information.
Sender
The sender address of the email is configured by thefrom
method.sendMail {
from "me@org.com"
…
}
from
method accepts one string value email address using the syntax of RFC822 Typical address syntax is of the form "user@host.domain"
or "Personal Name <user@host.domain>"
.If no value is provided for from
when sending an email, the default from address will be used.
3.2 Message Content
Message content is specified by either thetext
and/or html
methods that specify either the plain text or HTML content respectively.As of version 1.0, thebody
method that could be used to specify the message content has been deprecated (but is still there). Thebody
method requires the user to specify the content type of the message using a GSP directive such as:<%@ page contentType="text/html" %>
HTML Email
To send HTML mail you can use thehtml
method. This will set the content type of the message to text/html
.You can either supply a string value…sendMail { to "user@somewhere.org" subject "Hello John" html "<b>Hello</b> World" }
sendMail { to "user@somewhere.org" subject "Hello John" html view: "/emails/hello", model: [param1: "value1", param2: "value2"] }
html
.Plain Text Email
To send plain text mail you can use thetext
method. This will set the content type of the message to text/plain
.You can either supply a string value…sendMail { to "user@somewhere.org" subject "Hello John" text "Hello World" }
sendMail { to "user@somewhere.org" subject "Hello John" text view: "/emails/hello", model: [param1: "value1", param2: "value2"] }
text
.Plain Text and HTML
It is possible to send a multipart message that contains both plain text and HTML versions of the message. In this situation, the mail reading client is responsible for selecting the variant to display to the user.To do this, simply use both thehtml
and text
methods…sendMail { to "user@somewhere.org" subject "Hello John" text view: "/emails/text-hello", model: [param1: "value1", param2: "value2"] html view: "/emails/html-hello", model: [param1: "value1", param2: "value2"] }
Using Views
Both thetext
and html
methods support specifying a view to render to form the content. These are the accepted parameters:
- The view is the absolute path (or relative to the current controller if during a request) to the GSP, just like the existing Grails
render
method. - The plugin parameter is only necessary if the view you wish to render comes from a plugin, just like the existing Grails
render
method. - The model parameter is a map representing the model the GSP will see for rendering data, just like the existing Grails
render
method.
3.3 Attachments
The mail plugin is capable of adding attachments to messages as independent files and inline resources. To enable attachment support, you MUST indicate that the message is to be multipart as the first thing you do in the mail DSL.sendMail {
multipart true
}
File Attachments
The term file attachments here refers to the attachment being received as a file, not necessarily using a file in your application to form the attachment.The following methods are available in the mail DSL to attach files…// Bytes attach(String fileName, String contentType, byte[] bytes)// Files attach(File file) attach(String fileName, File file) attach(String fileName, String contentType, File file)// InputStream attach(String fileName, String contentType, InputStreamSource source)
- file name - what the email client will call the file
- content type - what mime type the email client will treat the file as
- content source - the actual attachment
byte[]
, File
, or InputStreamSource
as the content source.In the case of the variants that take a File
that do not specify a file name, the name of the file will be used.In the case of the variants that take a File
that do not specify a content type, the content type will be guessed based on the file extension.sendMail { mutipart true to "someone@org.com" attach "yourfile.txt", "text/plain", "Hello!" as byte[] }
Inline Attachments
It is also possible to attach content as inline resources. This is particularly useful in the case of html email where you wish to embed images in the message. In this case you specify a content id instead of a file name for the attachment and then reference this content id in your mail message.To attach an image as an inline resource you could do…sendMail { mutipart true to "someone@org.com" inline "logo", "image/jpeg", new File("logo.jpg") html view: "/email/welcome" }
cid:
(content id) namespace…<html> <body> <img src='cid:logo' /> <p>Welcome Aboard!</p> </body> </html>
// Bytes inline(String fileName, String contentType, byte[] bytes)// Files inline(File file) inline(String fileName, File file) inline(String fileName, String contentType, File file)// InputStream inline(String fileName, String contentType, InputStreamSource source)
- content id - the identifier of the resource
- content type - what mime type the email client will treat the content as
- content source - the actual content
byte[]
, File
, or InputStreamSource
as the content source.In the case of the variants that take a File
that do not specify a content id, the name of the file will be used.In the case of the variants that take a File
that do not specify a content type, the content type will be guessed based on the file extension.