Skip to content

Getting started with Email Manager

This guide explains two ways to start using Email Manager: generating a new application with Email Manager already integrated, or integrating it by hand into an existing application.

Quick Start with Craft

The fastest way to try Email Manager is to generate a new application with Craft, the AppJars project generator. Craft produces a runnable Spring Boot and Vaadin project with Email Manager already integrated, so none of the manual integration steps are needed.

  1. Open craft.appjars.com and select the Email Manager card in the Modules section. Other AppJars can be selected as well; Craft wires them together.
  2. Adjust the Project and Appearance settings if needed, and click Download project.
  3. Extract the downloaded archive and run docker compose up -d from the extracted folder. The first start takes a few minutes while the application image is built. To run the application with Maven instead, run mvn spring-boot:run.
  4. Open http://localhost:8080; Craft adds the Emails view to the navigation drawer. The Templates view is added to the navigation as described in Add the Views to the Navigation.

Sending email requires an SMTP server. Set the spring.mail.host, spring.mail.port, spring.mail.username and spring.mail.password properties, or the environment variables listed in the generated .env.example file: copy it to .env when the application runs with Docker Compose, or export the variables when it runs with Maven. The application starts without them, but emails cannot be delivered until they are set.

Craft also generates a scheduled job that sends the emails waiting in the queue. When Process Manager is selected as well, the queue is processed by a process that can be scheduled and triggered from the Processes view instead.

Unless User Manager or Issue Tracker is selected as well, the generated application has no login page and every view is accessible without signing in.

The Craft Project Generator page describes every option and the contents of the generated project. Continue with Testing the Application to try Email Manager.

Manual Integration

Prepare the Application

The following steps integrate Email Manager into an existing Spring Boot and Vaadin application. To follow them from a blank application, open Craft, leave every module unselected, and click Download project. Extract the archive, import it into your IDE of choice, and verify the application starts correctly by running the main class. A project generated by Craft already declares the AppJars repository, so the next step can be skipped.

Add the AppJars Repository

AppJars artifacts are published to the public AppJars Maven repository. Add it to your pom.xml so that Maven can resolve the AppJars dependencies:

<repositories>
    <repository>
        <id>appjars</id>
        <name>AppJars Public Repository</name>
        <url>https://maven.appjars.com</url>
        <releases>
            <enabled>true</enabled>
        </releases>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
    </repository>
</repositories>

Add the Dependencies

Given that it is a monolithic application, the following dependencies representing the three layers of the appjar must be added:

<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-email-manager-flow</artifactId>
</dependency>
<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-email-manager-data-impl</artifactId>
</dependency>
<dependency>
    <groupId>com.appjars</groupId>
    <artifactId>appjars-email-manager-business-impl</artifactId>
</dependency>

After adding them, build the application to confirm that the dependencies are resolved correctly.

Configure the Router Layout

Inject the RouteConfigurer provided by Email Manager and configure the router layout in a @PostConstruct method so that the appjar views share the same layout as the rest of the application:

@Autowired
@Qualifier("EmailManagerRouteConfigurer")
RouteConfigurer routeConfigurer;

@PostConstruct
public void configure() {
    routeConfigurer.setViewsRouterLayout(MainLayout.class);
}

The import for RouteConfigurer is com.appjars.emailmanager.flow.util.RouteConfigurer.

Add the Views to the Navigation

Add the Email Manager views to the application's navigation menu. Insert the following snippet at the end of the method createNavigation() in MainLayout, before returning nav:

nav.addItem(new SideNavItem("Emails", EmailCrudView.class, VaadinIcon.ENVELOPE.create()));
nav.addItem(new SideNavItem("Templates", TemplateCrudView.class, VaadinIcon.FILE_TEXT.create()));

The imports for the view classes are:

  • com.appjars.emailmanager.flow.view.EmailCrudView
  • com.appjars.emailmanager.flow.view.TemplateCrudView

The icons come from com.vaadin.flow.component.icon.VaadinIcon, which ships with Vaadin, so they need no additional dependency.

EmailCrudView is annotated with @PermitAll, so the appjar makes it available to any authenticated user. The view does not filter emails by user: whoever opens it sees and manages every email. Restricting it to a particular role, such as ADMIN, is the responsibility of the host application's security configuration (for example, a User Manager access rule on its route).

The application built in this guide has no security configuration, so the snippet above adds both items unconditionally. In an application with Vaadin security enabled, guard each nav.addItem(...) call so that the menu hides the items the current user cannot open. See Restricting Access to AppJar Views, and its Hiding Menu Items section for which check to use.

Note

In version 2.1.0, TemplateCrudView has no access annotation. An application that uses Vaadin access control, or User Manager access rules, must explicitly grant access to its route (em/templates by default), for example with a User Manager access rule. Otherwise the view is denied to every user, and an accessChecker.hasAccess(TemplateCrudView.class) guard returns false, which hides the Templates menu item.

Configure Application Properties

Add the following properties to application.properties:

spring.jpa.hibernate.ddl-auto=update
spring.jpa.generate-ddl=true

Email Manager sends messages through a mail server. Add the SMTP connection details:

spring.mail.host=<your-smtp-host>
spring.mail.port=587
spring.mail.username=<your-username>
spring.mail.password=<your-password>
spring.mail.properties.mail.smtp.auth=true
spring.mail.properties.mail.smtp.starttls.enable=true

Email Manager supports file attachments. By default it accepts up to five attachments per email, of at most 25 MB each, restricted to a list of common document, image and archive content types. All three bounds are configurable:

com.appjars.emailmanager.attachments.max-size=26214400
com.appjars.emailmanager.attachments.max-files=5
com.appjars.emailmanager.attachments.accepted-types=application/pdf,image/png,image/jpeg

Raise the servlet's own upload limits to at least the maximum attachment size, or the larger files are rejected before the appjar sees them:

spring.servlet.multipart.max-file-size=25MB
spring.servlet.multipart.max-request-size=25MB

Templates work without further configuration. The following optional properties bound the size of a template body and of a rendered template, in characters, and list the languages a template can be written in. Leave templates.locales unset to keep a single version of each template:

com.appjars.emailmanager.templates.max-body-size=262144
com.appjars.emailmanager.templates.max-rendered-size=1048576
com.appjars.emailmanager.templates.locales=en,es

Finally, add com.flowingcode and com.appjars to the list of whitelisted packages in application.properties:

vaadin.allowed-packages = com.vaadin,org.vaadin,com.example.demo,com.flowingcode,com.appjars

The org.vaadin entry also covers the HTML editor used to compose email and template bodies, so keep it in the list.

Note

The HTML editor loads its scripts from the application's own /assets/ path. Vaadin's Spring Security integration permits that path by default; an application with a custom Spring Security configuration must permit /assets/** as well, or the editor does not load.

Testing the Application

Start the application by running the main Spring Boot class. After it starts, open http://localhost:8080 and navigate to Emails in the menu. The application built in this guide has no security configuration, so no login is required.

Compose a new email by clicking the Create button, filling in the recipient address and subject, and optionally attaching files. Clicking Save stores the email with the Created status; it does not send it. Sending is a separate action, available from the actions menu on the email's row:

  • Send now delivers the email immediately, and its status changes to Sent or Send failed.
  • Add to queue changes its status to Send pending. Queued emails are sent in the background by MailSenderService, which runs only when the application schedules it, either as a Process Manager task or with a Spring @Scheduled method, as described in Background Sending. Without a schedule, a queued email stays in Send pending. A project generated by Craft already schedules it.

To try templates, navigate to Templates, click Create, write a subject and body that use a placeholder such as {{customerName}}, and save the template with a name. Then return to Emails, click Create, and click Apply template to fill in the subject and body from the template.