| From | 24 |To | 25 |Subject | 26 |Body | 27 |
|---|---|---|---|
| ${msg.from} | 31 |${msg.to} | 32 |${msg.subject} | 33 |${msg.body} | 34 |
63 | Congratulations, you have successfully started your first Grails application! At the moment 64 | this is the default page, feel free to modify it to either redirect to a controller or display 65 | whatever content you may choose. Below is a list of controllers that are currently deployed in 66 | this application, click on each to execute its default action: 67 |
68 | 69 | 79 |Welcome Aboard!
374 | 375 | 376 | ---- 377 | 378 | The following methods are available in the mail DSL to inline-attach files: 379 | 380 | [source,groovy] 381 | ---- 382 | // Bytes 383 | inline(String fileName, String contentType, byte[] bytes) 384 | 385 | // Files 386 | inline(File file) 387 | inline(String fileName, File file) 388 | inline(String fileName, String contentType, File file) 389 | 390 | // InputStream 391 | inline(String fileName, String contentType, InputStreamSource source) 392 | ---- 393 | 394 | There are 3 things that need to be provided when creating an inline attachment: 395 | 396 | * content id - the identifier of the resource 397 | * content type - what mime type the email client will treat the content as 398 | * content source - the actual content 399 | 400 | The Mail Plugin supports using either a `byte[]`, `File`, or https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/core/io/InputStreamSource.html[`InputStreamSource`] as the content source. 401 | 402 | 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. 403 | 404 | 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. 405 | 406 | 407 | [[testing]] 408 | == Testing 409 | 410 | Typically, you don't want to actually send email as part of your automated tests. Besides wrapping all calls to `sendMail` 411 | in an environment sensitive guard (which is a very bad idea), you can use one of the following techniques to deal with this. 412 | 413 | 414 | === Disabling Email Sending 415 | 416 | You can effectively disable email sending globally in your test by setting the following value in your application for 417 | the test environment. 418 | 419 | [source,groovy] 420 | ---- 421 | grails.mail.disabled = true 422 | ---- 423 | 424 | This will effectively cause all calls to `sendMail()` to be a non-operation, with a warning being logged that mail is 425 | disabled. The advantage of this technique is that it is cheap. The disadvantage is that it makes it impossible to test 426 | that email would be sent and to inspect any aspects of the sent mail. 427 | 428 | 429 | === Using an Override Address 430 | 431 | You can _override_ any and all recipient email addresses in `sendMail()` calls to force messages to be delivered to a 432 | certain mailbox. 433 | 434 | [source,groovy] 435 | ---- 436 | grails.mail.overrideAddress = 'test@myorg.com' 437 | ---- 438 | 439 | All `to`, `cc` and `bcc` addresses will be replaced by this value if set. The advantage of this mechanism is that it 440 | allows you to test using a real SMTP server. The disadvantage is that it requires a real SMTP server and makes it 441 | difficult to test address determination logic. 442 | 443 | 444 | === Using the Greenmail plugin 445 | 446 | The preferred approach is to use the existing https://github.com/gpc/greenmail[Grails Greenmail] plugin to run an 447 | in-memory SMTP server inside your application. This allows you to fully exercise your email sending code and to inspect 448 | sent email to assert correct values for recipient addresses etc. 449 | 450 | The advantage of this approach is that it is as close as possible to real world and gives you access to the sent email 451 | in your tests. The disadvantage is that it is another dependency. 452 | 453 | Consult the documentation for the plugin for more information. 454 | -------------------------------------------------------------------------------- /src/main/groovy/grails/plugins/mail/GrailsMailException.groovy: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2008 the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | package grails.plugins.mail 17 | 18 | import groovy.transform.CompileStatic 19 | import groovy.transform.InheritConstructors 20 | 21 | @InheritConstructors 22 | @CompileStatic 23 | class GrailsMailException extends RuntimeException {} 24 | -------------------------------------------------------------------------------- /src/main/groovy/grails/plugins/mail/MailAutoConfiguration.groovy: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2022-2025 the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | package grails.plugins.mail 17 | 18 | import grails.core.GrailsApplication 19 | import grails.plugins.GrailsPluginManager 20 | import grails.web.pages.GroovyPagesUriService 21 | import groovy.transform.CompileStatic 22 | import jakarta.mail.Session 23 | import org.grails.gsp.GroovyPagesTemplateEngine 24 | import org.springframework.beans.factory.annotation.Autowired 25 | import org.springframework.beans.factory.annotation.Qualifier 26 | import org.springframework.boot.autoconfigure.AutoConfiguration 27 | import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean 28 | import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty 29 | import org.springframework.boot.context.properties.EnableConfigurationProperties 30 | import org.springframework.context.annotation.Bean 31 | import org.springframework.jndi.JndiObjectFactoryBean 32 | import org.springframework.mail.MailSender 33 | import org.springframework.mail.javamail.JavaMailSender 34 | import org.springframework.mail.javamail.JavaMailSenderImpl 35 | 36 | @CompileStatic 37 | @AutoConfiguration 38 | @EnableConfigurationProperties(MailConfigurationProperties) 39 | class MailAutoConfiguration { 40 | 41 | @Bean 42 | @ConditionalOnMissingBean 43 | @ConditionalOnProperty(prefix = 'grails.mail', name = 'jndiName') 44 | JndiObjectFactoryBean mailSession(MailConfigurationProperties mailProperties) { 45 | def factory = new JndiObjectFactoryBean() 46 | factory.jndiName = mailProperties.jndiName 47 | return factory 48 | } 49 | 50 | @Bean 51 | @ConditionalOnMissingBean 52 | JavaMailSender mailSender( 53 | @Autowired(required = false) 54 | @Qualifier('mailSession') Session mailSession, 55 | MailConfigurationProperties mailProperties) { 56 | 57 | def mailSender = new JavaMailSenderImpl() 58 | if (mailProperties.host) { 59 | mailSender.host = mailProperties.host 60 | } else if (!mailProperties.jndiName) { 61 | def envHost = System.getenv()['SMTP_HOST'] 62 | if (envHost) { 63 | mailSender.host = envHost 64 | } else { 65 | mailSender.host = 'localhost' 66 | } 67 | } 68 | if (mailProperties.encoding) { 69 | mailSender.defaultEncoding = mailProperties.encoding 70 | } else if (!mailProperties.jndiName) { 71 | mailSender.defaultEncoding = 'utf-8' 72 | } 73 | if (mailSession != null) { 74 | mailSender.session = mailSession 75 | } 76 | if (mailProperties.port) { 77 | mailSender.port = mailProperties.port 78 | } 79 | if (mailProperties.username) { 80 | mailSender.username = mailProperties.username 81 | } 82 | if (mailProperties.password) { 83 | mailSender.password = mailProperties.password 84 | } 85 | if (mailProperties.protocol) { 86 | mailSender.protocol = mailProperties.protocol 87 | } 88 | if (mailProperties.props) { 89 | mailSender.javaMailProperties = mailProperties.props 90 | } 91 | return mailSender 92 | } 93 | 94 | @Bean 95 | @ConditionalOnMissingBean 96 | MailMessageBuilderFactory mailMessageBuilderFactory( 97 | MailSender mailSender, 98 | MailMessageContentRenderer mailMessageContentRenderer) { 99 | new MailMessageBuilderFactory(mailSender, mailMessageContentRenderer) 100 | } 101 | 102 | @Bean 103 | @ConditionalOnMissingBean 104 | MailMessageContentRenderer mailMessageContentRenderer( 105 | GroovyPagesTemplateEngine groovyPagesTemplateEngine, 106 | GroovyPagesUriService groovyPagesUriService, 107 | GrailsApplication grailsApplication, 108 | GrailsPluginManager pluginManager) { 109 | new MailMessageContentRenderer(groovyPagesTemplateEngine, groovyPagesUriService, grailsApplication, pluginManager) 110 | } 111 | 112 | @Bean 113 | @ConditionalOnMissingBean 114 | MailService mailService(MailConfigurationProperties mailConfigurationProperties, 115 | MailMessageBuilderFactory mailMessageBuilderFactory) { 116 | new MailService(mailConfigurationProperties, mailMessageBuilderFactory) 117 | } 118 | } 119 | -------------------------------------------------------------------------------- /src/main/groovy/grails/plugins/mail/MailConfigurationProperties.groovy: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2022-2025 the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * http://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | package grails.plugins.mail 17 | 18 | import org.springframework.boot.context.properties.ConfigurationProperties 19 | 20 | @ConfigurationProperties(PREFIX) 21 | class MailConfigurationProperties { 22 | 23 | public static final String PREFIX = 'grails.mail' 24 | 25 | boolean disabled 26 | String overrideAddress 27 | Defaults defaults = new Defaults() 28 | 29 | Integer poolSize 30 | String encoding 31 | String jndiName 32 | String protocol 33 | String host 34 | Integer port 35 | String username 36 | String password 37 | Properties props 38 | 39 | /** 40 | * We can't use 'default' as a groovy property name as it is a reserved keyword. 41 | * But it is possible to define a getter for it to make it compatible. 42 | */ 43 | Defaults getDefault() { 44 | return defaults 45 | } 46 | 47 | static class Defaults { 48 | String from 49 | String to 50 | } 51 | } 52 | -------------------------------------------------------------------------------- /src/main/groovy/grails/plugins/mail/MailGrailsPlugin.groovy: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2008-2025 the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | package grails.plugins.mail 17 | 18 | import grails.plugins.Plugin 19 | 20 | class MailGrailsPlugin extends Plugin { 21 | 22 | def grailsVersion = '7.0.0 > *' 23 | def author = 'The Grails team' 24 | def authorEmail = 'info@grails.org' 25 | def title = 'Provides Mail support to a running Grails application' 26 | def description = '''\ 27 | This plugin provides a MailService class as well as configuring the necessary beans within 28 | the Spring ApplicationContext. 29 | 30 | It also adds a "sendMail" method to all controller classes. A typical example usage is: 31 | 32 | sendMail { 33 | to 'fred@g2one.com','ginger@g2one.com' 34 | from 'john@g2one.com' 35 | cc 'marge@g2one.com', 'ed@g2one.com' 36 | bcc 'joe@g2one.com' 37 | subject 'Hello John' 38 | text 'this is some text' 39 | } 40 | '''.stripIndent(8) 41 | def documentation = 'https://grails-plugins.github.io/grails-mail' 42 | def license = 'Apache 2.0 License' 43 | def organization = [name: 'Grails Plugins', url: 'https://github.com/grails-plugins'] 44 | def developers = [ 45 | [name: 'Craig Andrews', email: 'candrews@integralblue.com'], 46 | [name: 'Luke Daley', email: 'ld@ldaley.com'], 47 | [name: 'Peter Ledbrook', email: 'p.ledbrook@cacoethes.co.uk'], 48 | [name: 'Jeff Brown', email: 'brownj@ociweb.com'], 49 | [name: 'Graeme Rocher', email: 'rocherg@ociweb.com'], 50 | [name: 'Marc Palmer', email: 'marc@grailsrocks.com'], 51 | [name: 'Søren Berg Glasius', email: 'soeren@glasius.dk'], 52 | [name: 'Mattias Reichel', email: 'mattias.reichel@gmail.com'] 53 | ] 54 | def issueManagement = [ 55 | system: 'GitHub', 56 | url: 'https://github.com/grails-plugins/grails-mail/issues' 57 | ] 58 | def scm = [ 59 | url: 'https://github.com/grails-plugins/grails-mail' 60 | ] 61 | def providedArtefacts = [PlainTextMailTagLib] 62 | } 63 | -------------------------------------------------------------------------------- /src/main/groovy/grails/plugins/mail/MailMessageBuilder.groovy: -------------------------------------------------------------------------------- 1 | /* 2 | * Copyright 2008-2025 the original author or authors. 3 | * 4 | * Licensed under the Apache License, Version 2.0 (the "License"); 5 | * you may not use this file except in compliance with the License. 6 | * You may obtain a copy of the License at 7 | * 8 | * https://www.apache.org/licenses/LICENSE-2.0 9 | * 10 | * Unless required by applicable law or agreed to in writing, software 11 | * distributed under the License is distributed on an "AS IS" BASIS, 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 | * See the License for the specific language governing permissions and 14 | * limitations under the License. 15 | */ 16 | package grails.plugins.mail 17 | 18 | import groovy.transform.CompileDynamic 19 | import groovy.transform.CompileStatic 20 | import groovy.util.logging.Slf4j 21 | import org.eclipse.angus.mail.smtp.SMTPMessage 22 | import org.springframework.core.io.ByteArrayResource 23 | import org.springframework.core.io.FileSystemResource 24 | import org.springframework.core.io.InputStreamSource 25 | import org.springframework.mail.MailMessage 26 | import org.springframework.mail.MailSender 27 | import org.springframework.mail.SimpleMailMessage 28 | import org.springframework.mail.javamail.JavaMailSender 29 | import org.springframework.mail.javamail.MimeMailMessage 30 | import org.springframework.mail.javamail.MimeMessageHelper 31 | import org.springframework.util.Assert 32 | import org.springframework.util.StringUtils 33 | 34 | import jakarta.mail.Message 35 | import jakarta.mail.internet.MimeMessage 36 | import jakarta.mail.internet.MimeUtility 37 | import java.util.concurrent.ExecutorService 38 | 39 | /** 40 | * Provides a DSL style interface to mail message sending/generation. 41 | * 42 | * If the builder is constructed without a MailMessageContentRenderer, it is incapable 43 | * of rendering GSP views into message content. 44 | */ 45 | @Slf4j 46 | @CompileStatic 47 | class MailMessageBuilder { 48 | 49 | final MailSender mailSender 50 | final MailMessageContentRenderer mailMessageContentRenderer 51 | 52 | final String defaultFrom 53 | final String defaultTo 54 | final String overrideAddress 55 | 56 | private MailMessage message 57 | private MimeMessageHelper helper 58 | private Locale locale 59 | 60 | private String textContent 61 | private String htmlContent 62 | private String envelopeFrom 63 | 64 | private int multipart = MimeMessageHelper.MULTIPART_MODE_NO 65 | private boolean async = false 66 | 67 | private List