3 Amazon Simple Email Service (AWS SES)

If you just want to send e-mails using your non-SES infrastructure, this plugin won't help you, I recommend you to use the great Grails Mail Plugin (http://grails.org/plugin/mail).

Unfortunately, SES does not provide a simple SMTP server address to connect and use, otherwise we could just configure the Grails Mail Plugin to use it. Instead of this, AWS provides a http web service for it.

But, if you really want to use Mail Plugin, you can configure AWS SES with a SMTP Bridge to connect to your SMTP server, but only if you're running Postfix or Sendmail locally. For doing this, check AWS SES Developer Guide.

REMBEMBER: You have to be subscribed to SES, if you are not yet, do it before using the plugin.

Attention: If you only subscribed to Amazon SES and still didn't get access for production using, you'll only be allowed to send e-mails 'from' AND 'to' emails that has been verified with amazon. So, you'll have to use the 'grails aws-ses-verify-email' for both sender and recipient adresses. After getting production access, this won't be needed.

3.1 Configuring the SES options

enabled

The plugin is enabled by default on all environments, you can set 'enabled=false' on some environments to disable email sending. This is useful on testing environments where integration tests runs.

catchall

If you set the 'catch all' address, it will override any other address you set in 'to', 'cc' and 'bcc' properties. This is useful when you have acceptance tests or other environments/uses that you want your mails to be sent, but not to the usual addresses, but to one and only one address.

Any attempt to send emails with this property configured, will send e-mails to the address configured, with no 'cc' and 'bcc' addresses.

from

The default 'from' address to be used. You can override this parameter in every call to the plugin, setting the 'from' parameter. As said before, this address have to be verified with AWS (check Gant scripts section to see how to do it).

region

Optional code to set the SES region to use. Provide string in all caps. Defaults to 'US_EAST_1'.

Regions available as of April 11th, 2014: US_EAST_1, US_WEST_2, EU_WEST_1

Configuration example

To configure it, you'll do the following inside the grails.plugin.aws section of your application Config.

grails {
   plugin {
      aws {
         ses {
            enabled = false
            catchall = "allmailforme@gmail.com"
            from = "my-verified-email@gmail.com"
            region "US_WEST_2"  //optional, defaults to US_EAST_1
         }
      }
   }
}

3.2 Sending text emails

def mailId = sesMail {
    from "origin@gmail.com"
    to "test-email@gmail.com"
    subject "test plain text mail"
    body "this is the e-mail content, sent at: (${new Date().format('dd/MM/yyyy HH:mm')})"
}

The sesMail returns an unique identifier for this e-mail at Amazon infrastructure, as this one:

0000012dcde0ea1c-d331d2ec-3972-4a6c-825f-fc980cde3352-000000

Amazon don't provide anything useful to do with this id yet, but I imagine that in a near future, you'll be able to retrieve if this email was delivered correctly, or if it was spammed or bounced. So, feel free to store it if you want to.

Closure parameters

AWS Credentials

As the S3 file upload support, you can override AWS credentials settings for sending mails. This is rare and unusual, but if you really need, do the same as in S3.

credentials "new-access-key", "new-secret-key"

Just remember, if this new AWS credentials belong to another AWS account, this account will have to be subscribed to SES service and have verified e-mails to send.

Defining the sender

As seen in the other topic, you can set this default address in the application Config, but if you want to explicitly set the address in each email you send, just override the from method:

from "my-other-email@gmail.com"

Defining recipient e-mails

To

To set the recipient e-mail, use the to method.

to "user@myapp.com"

You can send to multiple addresses doing this:

to "usermyapp.com", "user2myapp.com", "user3@myapp.com"

CC and BCC

To set CC and BCC addresses, you can do the same as to addresses:

cc "copied@myapp.com"

bcc "you-dont-know-me@myapp.com"

And again, for multiple addresses:

ccc "user1@myapp.com", "user2@myapp.com", "user3@myapp.com"

bcc "user4@myapp.com", "user5@myapp.com", "user6@myapp.com"

Setting the e-mail subject

To set the subject, following other parameters convention:

subject "Testing the AWS Plugin"

E-mail body

And finally, the e-mail body can be set with:

body "This is the text user will receive in the e-mail body"

Defining the reply-to address

You can set the reply-to header of your mail message using the replyTo closure parameter. And you can pass one string, or a list of e-mails that will be set as 'reply-to' header.

One e-mail

replyTo "my-other-email@gmail.com"

Multiple e-mails

replyTo "my-other-email-1gmail.com", "my-other-email-2gmail.com", "my-other-email-3@gmail.com"

Setting the e-mail charset

You can modify the email charset using the charset closure parameter. If this isn't specified, the default is UTF-8.

charset "charset "ISO-8859-1"

3.3 Sending HTML emails

sesMail {
   to "email@gmailcom"
   subject "testing html emails"
   html "<html><body><h3>HTML email</h3><strong>Strong text</strong></body></html>"
}

Using GSP templates to generate html emails

I bet you don't want to write all the HTML in your closure, so, you can design your e-mail in a grails template and use it to define the email content:

sesMail {
   to "email@gmailcom"
   subject "testing html emails"
   html g.render(template: "/email-templates/template", model: [name: "Lucas", now: new Date()])
}

This will render the /email-templates/_template.gsp passing the model map to the rendering engine. For example, let's imagine this file has the following content:

<html>
   <body>
      <h2>Testing e-mail templates</h2>
      <ul>
         <li>Name: ${name}</li>
         <li>Now: ${now.format('dd/MM/yyyy HH:mm')}</li>
      </ul>
   </body>
</html>

This will send the html e-mail with the content below rendered:

<html>
   <body>
      <h2>Testing e-mail templates</h2>
      <ul>
         <li>Name: Lucas</li>
         <li>Now: 28/01/2010 18:02</li>
      </ul>
   </body>
</html>

You can use both methods html and body to send e-mails with both content in it. This is usually the best approach, since user may not allowed his email client to render html emails. So, it is up to you.

3.4 Sending emails with attachments

It is simple, you just need to call the "attach" method in the sesMail closure with the full path to desired files, like below:

sesMail {
   to "email@gmailcom"
   subject "testing emails with one attachment"
   body "..."
   attach "/users/website/images/file1.jpg"
}

You can attach several files separating file paths with commas:

sesMail {
   to "email@gmailcom"
   subject "testing emails with one attachment"
   body "..."
   attach "/users/website/images/file1.jpg", "/users/website/images/file2.jpg", "/users/website/images/file3.jpg"
}