https://github.com/samply/common-mailing
https://github.com/samply/common-mailing
Last synced: 3 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/samply/common-mailing
- Owner: samply
- License: apache-2.0
- Created: 2020-11-05T08:19:06.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2022-04-13T01:54:52.000Z (about 3 years ago)
- Last Synced: 2024-12-30T07:14:07.756Z (5 months ago)
- Language: Java
- Size: 29.3 KB
- Stars: 0
- Watchers: 3
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Samply Common Mailing
This library offers utilities for building and sending HTML emails.
It provides a master template file that is used for all emails.
The content and footer for emails can be set by the projects that use this
library. The template engine is [Google Closure Templates][closuretemplates].
The configuration for email sending (connection to mail server etc.)
can be specified in an XML file, which is parsed
with the Samply Common Config library.
[closuretemplates]: https://developers.google.com/closure/templates/
## Usage
The configuration file for mail sending is named `mailSending.xml`.
You can either create a `MailSending` configuration object by reading the XML file
or set its values in Java Code.
MailSending mailSending = MailSender.loadMailSendingConfig("myproject");
In the documentation for the Samply Common Config library you can see where
the configuration file can be placed. The configuration is needed to create a
`MailSender` instance:
MailSender mailSender = new MailSender(mailSending);
An email builder combines different template files and generates the text:
String templateFolder = mailSending.getTemplateFolder();
EmailBuilder builder = new EmailBuilder(templateFolder);
builder.addTemplateFile("Footer.soy", "Footer");
builder.addTemplateFile("TestMailContent.soy", "TestMailContent");
You can write and add template files that provide implementations
for different parts of the email.
This is done with [Delegate Templates][deltemplates].
There are three delegate templates, namely `maincontent`,
`footer` and `greeting`. Setting a `maincontent` is mandatory, the other
templates are optional.
The greeting part has a default implementation, which should usually suffice.
*For a complete working example please take a look at the maven test folder
(`src/test/`).*
The template files must all be located in one folder whose
path must be specified in the configuration.
[deltemplates]: https://developers.google.com/closure/templates/docs/commands#delegates-with-variant
An `OutgoingEmail` object gets all information needed for writing the
email:
OutgoingEmail email = new OutgoingEmail();
email.addAddressee("[email protected]");
email.setSubject("Subject: Test");
email.putParameter("name", "Müller");
email.putParameter("title", "Prof. Dr.");
email.setLocale("de");
email.putParameter("testPar", "http://example.org");
email.setBuilder(builder);
The parameters `"name"` and `"title"` are used in the main template to
generate a standard personalized greeting, depending on the locale.
If no name is provided, you get an anonymous greeting.
All other parameters can be set to be used by the templates.
Now, after having set the parameters and specified the templates, the mail can
be sent:
mailSender.send(email);
## Build
Use maven to build the jar:
mvn clean package
Use it as a dependency:
de.samply
common-mailing
1.0.0-SNAPSHOT
## License
Copyright 2020 The Samply Development Community
Licensed 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
http://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.