Merge pull request #146 from mailjet/adds-transactional-email-builder

adds sending of typed transactional emails

Author: sdiakovskyi-gd

README.md

@@ -48,6 +48,10 @@ Check out all the resources and all the Java code examples in the [Offical Docum
 
 
 ## Release notes
+v5.1.0
+- downgraded OkHttpClient to v3.12 to be compatible with the current version in Spring Boot
+- adds [transactional email builder](src/test/java/com/mailjet/client/TransactionalEmailBuilderIT.java) to make possible sending messages easier 
+
 v5.0.0
 - migrated to more reliable OkHttpClient
 - removed ApiVersion from the MailjetClient configuration: Now the client will determine the needed API version from the resource itself.
@@ -66,7 +70,7 @@ Add the following in your `pom.xml`
         <dependency>
             <groupId>com.mailjet</groupId>
             <artifactId>mailjet-client</artifactId>
-            <version>5.0.0</version>
+            <version>5.1.0</version>
         </dependency>
     </dependencies>
 ```
@@ -80,7 +84,7 @@ export MJ_APIKEY_PUBLIC='your API key'
 export MJ_APIKEY_PRIVATE='your API secret'
 ```
 
-> Note: For the SMS API the authorization is based on a Bearer token. See information about it in the [SMS API](#sms-api) section of the readme.
+> Note: The SMS API authorization is based on a Bearer token. See information about it in the [SMS API](#sms-api) section of the readme.
 
 Initialize your [Mailjet][mailjet] Client:
 
@@ -97,7 +101,31 @@ Initialize your [Mailjet][mailjet] Client:
 
 ## Make your first call
 
-Here's an example on how to send an email:
+Here's an example on how to send a transactional email:
+```java
+        TransactionalEmail message1 = TransactionalEmail
+                .builder()
+                .to(new SendContact(senderEmail, "stanislav"))
+                .from(new SendContact(senderEmail, "Mailjet integration test"))
+                .htmlPart("<h1>This is the HTML content of the mail</h1>")
+                .subject("This is the subject")
+                .trackOpens(TrackOpens.ENABLED)
+                .attachment(Attachment.fromFile(attachmentPath))
+                .header("test-header-key", "test-value")
+                .customID("custom-id-value")
+                .build();
+
+        SendEmailsRequest request = SendEmailsRequest
+                .builder()
+                .message(message1) // you can add up to 50 messages per request
+                .build();
+
+        // act
+        SendEmailsResponse response = request.sendWith(client);
+
+```
+
+Or using an old JSONObject syntax:
 
 ```java
 package com.my.project;

pom.xml

@@ -6,7 +6,7 @@
     <!--General configuration -->
     <groupId>com.mailjet</groupId>
     <artifactId>mailjet-client</artifactId>
-    <version>5.0.0</version>
+    <version>5.1.0</version>
     <packaging>jar</packaging>
     <name>Mailjet Client</name>
     <description>A Mailjet API Client</description>
@@ -27,7 +27,7 @@
         <connection>scm:git:https://github.com/mailjet/mailjet-apiv3-java.git</connection>
         <developerConnection>scm:git:https://github.com/mailjet/mailjet-apiv3-java.git</developerConnection>
         <url>git@github.com:mailjet/mailjet-apiv3-java.git</url>
-        <tag>mailjet-client-5.0.0</tag>
+        <tag>mailjet-client-5.1.0</tag>
     </scm>
     <!--License-->
     <licenses>
@@ -64,6 +64,11 @@
             <artifactId>json</artifactId>
             <version>20190722</version>
         </dependency>
+        <dependency>
+            <groupId>com.google.code.gson</groupId>
+            <artifactId>gson</artifactId>
+            <version>2.8.6</version>
+        </dependency>
         <dependency>
             <groupId>org.projectlombok</groupId>
             <artifactId>lombok</artifactId>

src/main/java/com/mailjet/client/MailjetClient.java

@@ -35,7 +35,7 @@ public class MailjetClient {
     private ClientOptions _options;
     private OkHttpClient _client;
 
-    private static final String userAgent = "mailjet-apiv3-java/v5.0.0";
+    private static final String userAgent = "mailjet-apiv3-java/v5.1.0";
 
     /**
      * Deprecated - please, use MailjetClient(ClientOptions clientOptions) ctor instead
@@ -67,6 +67,7 @@ public MailjetClient(String token) {
 
     /**
      * Create a new Instance of the MailjetClient class with given options
+     * @param clientOptions object that contains options for the given client instance
      */
     public MailjetClient(ClientOptions clientOptions) {
         _options = clientOptions;
@@ -179,7 +180,7 @@ private MailjetResponse parseResponse(MailjetRequest request, Response okHttpRes
         final String json = MailjetResponseUtil.isValidJSON(responseBody) ?
                 responseBody : new JSONObject().put("status", responseStatusCode).toString();
 
-        return new MailjetResponse(responseStatusCode, new JSONObject(json));
+        return new MailjetResponse(responseStatusCode, json);
     }
 
     private static OkHttpClient createDefaultOkHttpClient(){

src/main/java/com/mailjet/client/MailjetRequest.java

@@ -339,8 +339,8 @@ public String queryString() throws UnsupportedEncodingException {
 
     /**
      * Add a property to the body JSONObject
-     * @param key
-     * @param value
+     * @param key property name
+     * @param value property value
      * @return the request itself
      */
     public MailjetRequest property(String key, Object value) {

src/main/java/com/mailjet/client/MailjetResponse.java

@@ -15,70 +15,74 @@
  */
 public class MailjetResponse {
 
-    private JSONObject _rawResponse;
-    private int _status;
+    private final JSONObject responseObject;
+    private final String rawResponse;
+    private final int status;
 
-    public MailjetResponse(int status, JSONObject obj) {
-        _rawResponse = obj;
-        _status = status;
+    public MailjetResponse(int status, String rawResponse) {
+        responseObject = new JSONObject(rawResponse);
+        this.rawResponse = rawResponse;
+        this.status = status;
     }
-
-    public MailjetResponse(JSONObject object) {
-        _rawResponse = object;
-        _status = 0;
-    }
-    
+    /**
+     * @return HTTP status code returned by Mailjet server
+     */
     public int getStatus() {
-        return _status;
+        return status;
     }
-    
+
+    /**
+     * @return Raw response string sent by Mailjet server
+     */
+    public String getRawResponseContent() { return rawResponse; }
+
     public JSONArray getData() {
-        if (_rawResponse.has("Data")) {
-            return _rawResponse.getJSONArray("Data");
-        } else if (_rawResponse.has("Sent")) {
-            return _rawResponse.getJSONArray("Sent");
-        } else if (_rawResponse.has("Messages")) {
-            return _rawResponse.getJSONArray("Messages");
+        if (responseObject.has("Data")) {
+            return responseObject.getJSONArray("Data");
+        } else if (responseObject.has("Sent")) {
+            return responseObject.getJSONArray("Sent");
+        } else if (responseObject.has("Messages")) {
+            return responseObject.getJSONArray("Messages");
         } else {
-            return (new JSONArray()).put(_rawResponse);
+            return (new JSONArray()).put(responseObject);
         }
     }
 
     public int getTotal() {
-        if (_rawResponse.has("Total")) {
-            return _rawResponse.getInt("Total");
+        if (responseObject.has("Total")) {
+            return responseObject.getInt("Total");
         } else {
             return 0;
         }
     }
 
     public String getString(String key) throws MailjetException {
         try {
-            return _rawResponse.getString(key);
+            return responseObject.getString(key);
         } catch (NullPointerException e) {
            throw new MailjetException("No entry found for key: " + key);
         }
     }
 
     public int getInt(String key) throws MailjetException {
         try {
-            return _rawResponse.getInt(key);
+            return responseObject.getInt(key);
         } catch (NullPointerException e) {
             throw new MailjetException("No entry found for key: " + key);
         }
     }
 
     public JSONArray getJSONArray(String key) throws MailjetException {
         try {
-            return _rawResponse.getJSONArray(key);
+            return responseObject.getJSONArray(key);
         } catch (NullPointerException e) { 
             throw new MailjetException("No entry found for key: " + key);
         }
     }
 
     public int getCount() {
-        if (_rawResponse.has("Count")) {
-            return _rawResponse.getInt("Count");
+        if (responseObject.has("Count")) {
+            return responseObject.getInt("Count");
         } else {
             return 0;
         }

src/main/java/com/mailjet/client/MailjetResponseUtil.java

@@ -16,6 +16,7 @@ public final class MailjetResponseUtil {
 	private static final int INTERNAL_SERVER_ERROR_STATUS = 500;
 	private static final int BAD_REQUEST_ERROR_STATUS = 400;
 	private static final int UNAUTHORIZED_STATUS = 401;
+	public static final int CREATED_STATUS = 201;
 
 	private static final String UNAUTHORIZED_MESSAGE = "Unauthorized. Please,verify your access key and access secret key or token for the given account";
 	private static final String TOO_MANY_REQUESTS_EXCEPTION = "Too Many Requests";
@@ -42,7 +43,7 @@ public static boolean isValidJSON(String json) {
 		return json != null && json.trim().startsWith("{") && json.trim().endsWith("}");
 	}
 
-	/*
+	/**
 	* Specific API methods support partial success
 	* like, if we send multiple emails in bulk
 	* and the one is failed and other one sent successfully

src/main/java/com/mailjet/client/helpers/StringMapSerializer.java

@@ -0,0 +1,31 @@
+package com.mailjet.client.helpers;
+
+import com.google.gson.JsonElement;
+import com.google.gson.JsonSerializationContext;
+import com.google.gson.JsonSerializer;
+
+import java.lang.reflect.Type;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Serializes {@code Map<String, Object> as Map<String, String>}
+ * where String value is JSON representation of the value
+ */
+public class StringMapSerializer implements JsonSerializer<Map> {
+    @Override
+    public JsonElement serialize(Map map, Type type, JsonSerializationContext jsonSerializationContext) {
+        Map<String, String> stringMap = new HashMap<>(map.size());
+
+        for (Object entry: map.entrySet()) {
+            Map.Entry<String, Object> objectEntry = (Map.Entry<String, Object>) entry;
+
+            String key = objectEntry.getKey();
+            String value = jsonSerializationContext.serialize(objectEntry.getValue()).toString();
+
+            stringMap.put(key, value);
+        }
+
+        return jsonSerializationContext.serialize(stringMap);
+    }
+}

src/main/java/com/mailjet/client/resource/Emailv31.java

@@ -19,6 +19,7 @@ public class Emailv31 {
 
     public static String MESSAGES = "Messages";
     public static String SANDBOX_MODE = "SandboxMode";
+    public static String ADVANCE_ERROR_HANDLING = "AdvanceErrorHandling";
 
     public static class Message {
       public static String EMAIL = "Email";

src/main/java/com/mailjet/client/transactional/Attachment.java

@@ -0,0 +1,58 @@
+package com.mailjet.client.transactional;
+
+import lombok.Builder;
+import lombok.Data;
+
+import java.io.File;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Base64;
+
+@Data
+@Builder
+public class Attachment {
+    /**
+     * The full name of the file (including the file extension).
+     */
+    private String filename;
+
+    /**
+     * Defines the type of content being sent out using a MIME type.
+     * See the official MIME type list for additional information. https://www.iana.org/assignments/media-types/media-types.xhtml
+     */
+    private String contentType;
+
+    /**
+     * Base64 encoded content of the attached file
+     */
+    private String base64Content;
+
+    /**
+     *  Name of the cid to be inserted in the HTML content of the message.
+     *  The value must be unique across all inline attachments in the message.
+     *  The value valid ONLY for InlinedAttachment
+     */
+    private String contentID;
+
+    /**
+     * Creates an attachment from the file
+     * @param pathToFile full path to the file
+     * @return constructed Attachment object
+     * @throws IOException if something wrong with reading file under the given path
+     */
+    public static Attachment fromFile(String pathToFile) throws IOException {
+        File file = new File(pathToFile);
+        Path path = file.toPath();
+
+        String mimeType = Files.probeContentType(path);
+        byte[] fileContent = Files.readAllBytes(path);
+        String base64Content = Base64.getEncoder().encodeToString(fileContent);
+
+        return new AttachmentBuilder()
+                .base64Content(base64Content)
+                .contentType(mimeType)
+                .filename(path.getFileName().toString())
+                .build();
+    }
+}

src/main/java/com/mailjet/client/transactional/SendContact.java

@@ -0,0 +1,24 @@
+package com.mailjet.client.transactional;
+
+public class SendContact {
+    /**
+     * Represents an object with email and name (optional) that can be used as To, Cc, Bcc, From etc
+     * @param email email address
+     * @param name the display name of the person (Will be displayed in email like {@code NAME <EMAIL>}
+     */
+    public SendContact(String email, String name) {
+        this(email);
+        Name = name;
+    }
+
+    /**
+     * Represents an object with email that can be used as To, Cc, Bcc, From etc
+     * @param email email address
+     */
+    public SendContact(String email) {
+        Email = email;
+    }
+
+    private String Name;
+    private String Email;
+}