From 7d6972d8ae88f2aec77d87fdbfe3d8952d1f8461 Mon Sep 17 00:00:00 2001 From: GPC Deployer Date: Wed, 22 Jan 2025 12:40:29 +0000 Subject: [PATCH] Deploying to gh-pages - 12:40:29 --- snapshot/index.html | 1212 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 1093 insertions(+), 119 deletions(-) diff --git a/snapshot/index.html b/snapshot/index.html index 4b5a97e..7bc69d7 100644 --- a/snapshot/index.html +++ b/snapshot/index.html @@ -1,128 +1,1102 @@ - - - - - - - Grails Mail Plugin 5.0.0-SNAPSHOT - - - - - + def create = { + // create user - - +
+
+
class PersonController {
 
-
-
+ def mailService + def create = { + // create user - - - - - -
-
+ mailService.sendMail { + from 'admin@mysystem.com' + subject 'New user' + text 'A new user has been created' + } + } +} +
+ +
+

The sendMail() method takes a single Closure argument that uses a DSL (Domain Specific Language) to configure the +message to be sent. This section describes the aspects of the DSL. +=== Recipients

+
+
+

The DSL provides to, 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'
+    // ...
+}
+
+
+
+

All methods take one or more String values that are email addresses using the syntax +of http://www.ietf.org/rfc/rfc822.txt.[RFC822]. Typical address syntax is of the form "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'
+    // …
+}
+
+
+
+

If no value is provided for 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. +
+
+
+

3.1. Sender

+
+

The sender address of the email is configured with the from method.

+
+
+
+
sendMail {
+    from 'me@org.com'
+    // …
+}
+
+
+
+

The from method accepts one String value email address using the syntax of +https://www.ietf.org/rfc/rfc822.txt.[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. +== Message Content

+
+
+

Message content is specified by either the text and/or html methods that specify either the plain-text or HTML +content respectively.

+
+
+ + + + + +
+ + +As of version 1.0, the body method that could be used to specify the message content has been deprecated. +The body method requires the user to specify the content type of the message using a GSP directive such as: +
+
+
+
+
<%@ page contentType="text/html" %>
+
+
+
+
+

3.2. HTML Email

+
+

To send HTML email you can use the html 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'
+}
+
+
+
+

Or a view to render to form the content:

+
+
+
+
sendMail {
+    to 'user@somewhere.org'
+    subject 'Hello John'
+    html view: '/emails/hello', model: [param1: 'value1', param2: 'value2']
+}
+
+
+
+

See the section on using views for more details of the parameters to this version of html.

+
+
+
+

3.3. Text Email (plain-text)

+
+

To send plain-text email you can use the text 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'
+}
+
+
+
+

Or a view to render to form the content:

+
+
+
+
sendMail {
+    to 'user@somewhere.org'
+    subject 'Hello John'
+    text view: '/emails/hello', model: [param1: 'value1', param2: 'value2']
+}
+
+
+
+

See the section on using views for more details of the parameters to this version of text.

+
+
+
+

3.4. 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 email-reading client is responsible for selecting the variant to display to the user.

+
+
+

To do this, simply use both the html 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']
+}
+
+
+
+
+

3.5. Using Views

+
+

Both the text 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. +== 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
+}
+
+
+
+
+

3.6. 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)
 
-                        (Quick Reference)
+// Files
+attach(File file)
+attach(String fileName, File file)
+attach(String fileName, String contentType, File file)
 
-                        

-                            
Grails Mail Plugin

-                            
Authors: The Grails Team

-                            
Version: 5.0.0-SNAPSHOT

-                            
-                        

+// InputStream
+attach(String fileName, String contentType, InputStreamSource source)
+
+
+
+

There are 3 things that need to be provided when creating a file attachment:

+
+
+
    +
  • +

    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

    +
    • +
+
+
+

The Mail Plugin supports using either a 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 {
+    multipart true
+    to 'someone@org.com'
+    attach 'yourfile.txt', 'text/plain', 'Hello!' as byte[]
+}
+
+
+
+
+

3.7. 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 {
+    multipart true
+    to 'someone@org.com'
+    inline 'logo', 'image/jpeg', new File('logo.jpg')
+    html view: '/email/welcome'
+}
+
+
+
+

Then in your view you reference the inline attachment using the cid: (content id) namespace:

+
+
+
+
<html>
+  <body>
+    <img src="cid:logo" />
+    <p>Welcome Aboard!</p>
+  </body>
+</html>
+
+
+
+

The following methods are available in the mail DSL to inline-attach files:

+
+
+
+
// Bytes
+inline(String fileName, String contentType, byte[] bytes)
 
-                        
-                        

-                            
Table of Contents

-                            
-                            
1Introduction

-                            
-                            
2Configuration

-                            
-                            
2.1SMTP Server Configuration

-                            
-                            
2.2Defaults Configuration

-                            
-                            
2.3Other Configuration

-                            
-                            
3Sending Email

-                            
-                            
3.1Sender And Recipient

-                            
-                            
3.2Message Content

-                            
-                            
3.3Attachments

-                            
-                            
4Testing

-                            
-                            

-                        

-                        
-                        
-
-
-
-
- Quick Reference - (hide) -
-
- -
-
-
+// Files +inline(File file) +inline(String fileName, File file) +inline(String fileName, String contentType, File file) - - - - - - - - +// InputStream +inline(String fileName, String contentType, InputStreamSource source) + + +
+

There are 3 things that need to be provided when creating an inline attachment:

+
+
+ +
+
+

The Mail Plugin supports using either a 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.

+
+ + + +
+

4. Testing

+
+
+

Typically, you don’t want to actually send email as part of your automated tests. Besides wrapping all calls to sendMail +in an environment sensitive guard (which is a very bad idea), you can use one of the following techniques to deal with this.

+
+
+

4.1. Disabling Email Sending

+
+

You can effectively disable email sending globally in your test by setting the following value in your application for +the test environment.

+
+
+
+
grails.mail.disabled = true
+
+
+
+

This will effectively cause all calls to sendMail() to be a non-operation, with a warning being logged that mail is +disabled. The advantage of this technique is that it is cheap. The disadvantage is that it makes it impossible to test +that email would be sent and to inspect any aspects of the sent mail.

+
+
+
+

4.2. Using an Override Address

+
+

You can override any and all recipient email addresses in sendMail() calls to force messages to be delivered to a +certain mailbox.

+
+
+
+
grails.mail.overrideAddress = 'test@myorg.com'
+
+
+
+

All to, cc and bcc addresses will be replaced by this value if set. The advantage of this mechanism is that it +allows you to test using a real SMTP server. The disadvantage is that it requires a real SMTP server and makes it +difficult to test address determination logic.

+
+
+
+

4.3. Using the Greenmail plugin

+
+

The preferred approach is to use the existing Grails Greenmail plugin to run an +in-memory SMTP server inside your application. This allows you to fully exercise your email sending code and to inspect +sent email to assert correct values for recipient addresses etc.

+
+
+

The advantage of this approach is that it is as close as possible to real world and gives you access to the sent email +in your tests. The disadvantage is that it is another dependency.

+
+
+

Consult the documentation for the plugin for more information.

+
+
+
+
+ + + + + \ No newline at end of file