Merge pull request vert-x#12 from alexlehm/mail_examples

added mail-examples based on the refactored client/service interface

README.adoc

@@ -125,5 +125,12 @@ The link:unit-examples/README.adoc[Vert.x Unit examples] shows how to use Vert.x
 
 TODO
 
+=== Mail examples
 
+The link:mail-examples/README.adoc[Vert.x Mail examples]
+contains a few examples using Vert.x Mail
 
+The mail examples show different ways to create the mail message and send it via
+tls, ssl etc. The examples either use `localhost:25` to send a mail or use host
+`mail.example.com`. To actually run the examples you will have to change the
+mail server and the user credentials in the `MailLogin` example.

mail-examples/README.adoc

@@ -0,0 +1,47 @@
+= Vert.x Mail examples
+
+Here you'll find some examples how to use Vert.x mail-service to send mails
+to a SMTP server either from the local machine or via the event bus on another
+machine.
+
+The examples use a few different configs
+
+== link:src/main/java/io/vertx/example/mail/MailLocalhost.java[MailLocalhost]
+
+Send a mail to `localhost:25`, e.g. to postfix running on the local machine
+
+== link:src/main/java/io/vertx/example/mail/MailLogin.java[MailLogin]
+
+Send a mail to an external smtp server (e.g. googlemail, sendgrid, aol etc)
+requiring a login and enforcing use of TLS. The operation will fail if either
+the account is not set or the server doesn't announce STARTTLS capability.
+
+The login will currently use DIGEST-MD5, CRAM-MD5, PLAIN and LOGIN in order of
+preference, if the server announces AUTH but you don't need it (e.g. if you are
+authenticated by a local ip address) turn login off with `LoginOption.DISABLE`
+To specifically select a AUTH method or define the order of preference, you
+can do `setAuthMethods("METHOD1 METHOD2")`.
+
+== link:src/main/java/io/vertx/example/mail/MailEB.java[MailEB]
+
+Send a mail via the event bus to another vert.x instance registered as
+vertx.mail. This will use the config set by the service and doesn't use a local
+config object.
+
+This example shows how to leave out the From address in a mail but setting
+the bounceAddress property instead.
+
+The service listening on the event bus can be started with
+
+    vertx run service:io.vertx.mail-service
+
+and vertx will pick up the package from maven and start it with default config.
+
+== link:src/main/java/io/vertx/example/mail/MailHeaders.java[MailHeaders]
+
+Send a mail with supplied headers (e.g. Received, Message-ID, Reply-To)
+
+This test uses a SSL connect to the mail server using Port 465 (which is
+actually deprecated, but is supported by many mail servers e.g. googlemail
+and AOL support port 465). The preferred way to send secure mails is TLS
+required and port 587.

mail-examples/pom.xml

@@ -0,0 +1,39 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <parent>
+    <groupId>io.vertx</groupId>
+    <artifactId>vertx-examples</artifactId>
+    <version>3.0.0-SNAPSHOT</version>
+  </parent>
+  <artifactId>mail-examples</artifactId>
+  <dependencies>
+    <dependency>
+      <groupId>io.vertx</groupId>
+      <artifactId>vertx-mail-client</artifactId>
+      <version>3.0.0-SNAPSHOT</version>
+    </dependency>
+    <dependency>
+      <groupId>io.vertx</groupId>
+      <artifactId>vertx-mail-service</artifactId>
+      <version>3.0.0-SNAPSHOT</version>
+    </dependency>
+  </dependencies>
+  <build>
+    <pluginManagement>
+      <plugins>
+        <!-- We specify the Maven compiler plugin as we need to set it to Java 1.8 -->
+        <plugin>
+          <artifactId>maven-compiler-plugin</artifactId>
+          <version>3.1</version>
+          <configuration>
+            <source>1.8</source>
+            <target>1.8</target>
+            <compilerArgs>
+              <arg>-Acodetrans.output=${basedir}/src/main</arg>
+            </compilerArgs>
+          </configuration>
+        </plugin>
+      </plugins>
+    </pluginManagement>
+  </build>
+</project>

mail-examples/src/main/java/io/vertx/example/mail/MailEB.java

@@ -0,0 +1,33 @@
+package io.vertx.example.mail;
+
+import io.vertx.core.AbstractVerticle;
+import io.vertx.ext.mail.MailMessage;
+import io.vertx.ext.mail.MailService;
+
+/**
+ * send a mail via event bus to the mail service running on another machine
+ *
+ * @author <a href="http://oss.lehmann.cx/">Alexander Lehmann</a>
+ *
+ */
+public class MailEB extends AbstractVerticle {
+
+  public void start() {
+    MailService mailService = MailService.createEventBusProxy(vertx, "vertx.mail");
+
+    MailMessage email = new MailMessage()
+      .setBounceAddress("[email protected]")
+      .setTo("[email protected]")
+      .setSubject("this message has no content at all");
+
+    mailService.sendMail(email, result -> {
+      if (result.succeeded()) {
+        System.out.println(result.result());
+      } else {
+        System.out.println("got exception");
+        result.cause().printStackTrace();
+      }
+    });
+  }
+
+}

mail-examples/src/main/java/io/vertx/example/mail/MailHeaders.java

@@ -0,0 +1,48 @@
+package io.vertx.example.mail;
+
+import io.vertx.core.AbstractVerticle;
+import io.vertx.core.MultiMap;
+import io.vertx.core.http.CaseInsensitiveHeaders;
+import io.vertx.ext.mail.MailConfig;
+import io.vertx.ext.mail.MailMessage;
+import io.vertx.ext.mail.MailClient;
+
+import java.util.Arrays;
+
+/**
+ * send a mail via a smtp service using SSL we add a few headers to the mail (this can be used for example for mail api
+ * headers e.g. from mailgun or sendgrid or to add Reply-To and custom Received headers)
+ * <p>
+ * you can either supply all headers (setFixedHeaders(true)) or give a set of headers to be set over the headers that
+ * are set for the mime message (Message-ID, From, To etc)
+ *
+ * @author <a href="http://oss.lehmann.cx/">Alexander Lehmann</a>
+ */
+public class MailHeaders extends AbstractVerticle {
+
+  public void start() {
+    MailConfig mailConfig = new MailConfig("smtp.example.com", 465).setSsl(true);
+
+    MailClient mailClient = MailClient.create(vertx, mailConfig);
+
+    MailMessage email = new MailMessage()
+      .setFrom("[email protected]")
+      .setTo(Arrays.asList("[email protected]", "[email protected]", "[email protected]"));
+
+    MultiMap headers = new CaseInsensitiveHeaders();
+
+    headers.add("X-Mailer", "Vert.x Mail-Client 3.0");
+    headers.add("Message-ID", "[email protected]");
+    headers.add("Reply-To", "[email protected]");
+    headers.add("Received", "by vertx mail service");
+    headers.add("Received", "from [192.168.1.1] by localhost");
+
+    email.setHeaders(headers);
+    email.setText("This message should have a custom Message-ID");
+
+    mailClient.sendMail(email, result -> {
+      System.out.println("mail is finished");
+    });
+  }
+
+}

mail-examples/src/main/java/io/vertx/example/mail/MailLocalhost.java

@@ -0,0 +1,41 @@
+package io.vertx.example.mail;
+
+import io.vertx.core.AbstractVerticle;
+import io.vertx.ext.mail.MailConfig;
+import io.vertx.ext.mail.MailMessage;
+import io.vertx.ext.mail.MailClient;
+
+import java.util.Arrays;
+
+/**
+ * send a mail with default config via localhost:25
+ *
+ * @author <a href="http://oss.lehmann.cx/">Alexander Lehmann</a>
+ */
+public class MailLocalhost extends AbstractVerticle {
+
+  @Override
+  public void start() {
+
+    MailClient mailClient = MailClient.create(vertx, new MailConfig());
+
+    MailMessage email = new MailMessage()
+      .setFrom("[email protected] (Sender)")
+      .setTo(Arrays.asList(
+        "[email protected] (User Name)",
+        "[email protected] (Another User)"))
+      .setBounceAddress("[email protected] (Bounce)")
+      .setSubject("Test email")
+      .setText("this is a test email");
+
+    mailClient.sendMail(email, result -> {
+      if (result.succeeded()) {
+        System.out.println(result.result());
+      } else {
+        System.out.println("got exception");
+        result.cause().printStackTrace();
+      }
+    });
+  }
+
+}

mail-examples/src/main/java/io/vertx/example/mail/MailLogin.java

@@ -0,0 +1,65 @@
+package io.vertx.example.mail;
+
+import io.vertx.core.AbstractVerticle;
+import io.vertx.core.buffer.Buffer;
+import io.vertx.ext.mail.LoginOption;
+import io.vertx.ext.mail.MailAttachment;
+import io.vertx.ext.mail.MailConfig;
+import io.vertx.ext.mail.MailMessage;
+import io.vertx.ext.mail.MailClient;
+import io.vertx.ext.mail.StartTLSOptions;
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * send a mail via a smtp server requiring TLS and Login we use an attachment and a text/html alternative mail body
+ * <p>
+ * Please put in your actual mail server and account to run this example
+ *
+ * @author <a href="http://oss.lehmann.cx/">Alexander Lehmann</a>
+ */
+public class MailLogin extends AbstractVerticle {
+
+  public void start() {
+    MailConfig mailConfig = new MailConfig("smtp.example.com", 587, StartTLSOptions.REQUIRED, LoginOption.REQUIRED)
+      .setAuthMethods("PLAIN")
+      .setUsername("username")
+      .setPassword("password");
+
+    MailClient mailClient = MailClient.create(vertx, mailConfig);
+
+    Buffer image = vertx.fileSystem().readFileBlocking("logo-white-big.png");
+
+    MailMessage email = new MailMessage()
+      .setFrom("[email protected]")
+      .setTo("[email protected]")
+      .setCc("[email protected]")
+      .setBcc("[email protected]")
+      .setBounceAddress("[email protected]")
+      .setSubject("Test email with HTML")
+      .setText("this is a message")
+      .setHtml("<a href=\"http://vertx.io\">vertx.io</a>");
+
+    List<MailAttachment> list = new ArrayList<MailAttachment>();
+
+    list.add(new MailAttachment()
+      .setData(image)
+      .setName("logo-white-big.png")
+      .setContentType("image/png")
+      .setDisposition("inline")
+      .setDescription("logo of vert.x web page"));
+
+    email.setAttachment(list);
+
+    mailClient.sendMail(email, result -> {
+      if (result.succeeded()) {
+        System.out.println(result.result());
+      } else {
+        System.out.println("got exception");
+        result.cause().printStackTrace();
+      }
+    });
+  }
+
+}

pom.xml

@@ -21,6 +21,7 @@
     <module>examples-utils</module>
     <module>unit-examples</module>
     <module>metrics-examples</module>
+    <module>mail-examples</module>
   </modules>