Add email previews functionality

.github/workflows/build.yml

@@ -5,9 +5,9 @@ name: CI
 
 on:
   push:
-    branches: [ master ]
+    branches: [ main ]
   pull_request:
-    branches: [ master ]
+    branches: [ main ]
   workflow_dispatch:
 
 concurrency: 

pom.xml

@@ -25,7 +25,7 @@
   <licenses>
     <license>
       <name>MIT license</name>
-      <url>https://github.com/mailosaur/mailosaur-java/blob/master/LICENSE</url>
+      <url>https://github.com/mailosaur/mailosaur-java/blob/main/LICENSE</url>
     </license>
   </licenses>
 

src/main/java/com/mailosaur/Files.java

@@ -36,4 +36,17 @@ public byte[] getEmail(String messageId) throws MailosaurException, IOException
     	return client.requestFile("GET", "api/files/email/" + messageId).toByteArray();
     }
 
+    /**
+     * Downloads a screenshot of your email rendered in a real email client. Simply supply
+     * the unique identifier for the required preview.
+     *
+     * @param previewId The identifier of the email preview to be downloaded.
+     * @throws MailosaurException Thrown if Mailosaur responds with an error.
+     * @throws IOException Unexpected exception.
+     * @return The byte array if successful.
+     */
+    public byte[] getPreview(String previewId) throws MailosaurException, IOException {
+        return client.requestFile("GET", "api/files/previews/" + previewId).toByteArray();
+    }
+
 }

src/main/java/com/mailosaur/MailosaurClient.java

@@ -58,6 +58,7 @@ public MailosaurClient(String apiKey, String baseUrl) {
         this.servers = new Servers(this);
         this.usage = new Usage(this);
         this.devices = new Devices(this);
+        this.previews = new Previews(this);
     }
 
 	/**
@@ -137,6 +138,19 @@ public Usage usage() {
     public Devices devices() {
         return this.devices;
     }
+
+    /**
+     * Email Previews operations
+     */
+    private Previews previews;
+
+    /**
+     * Gets Email Previews operations.
+     * @return Email Previews operations.
+     */
+    public Previews previews() {
+        return this.previews;
+    }
 
     public HttpResponse request(String method, String url) throws MailosaurException {
     	return request(method, url, null);

src/main/java/com/mailosaur/Messages.java

@@ -586,7 +586,20 @@ public Message forward(String id, MessageForwardOptions messageForwardOptions) t
      * @return the Message object if successful.
      */
     public Message reply(String id, MessageReplyOptions messageReplyOptions) throws IOException, MailosaurException {
-    	return client.request("POST", "api/messages/" + id + "/reply", messageReplyOptions).parseAs(Message.class);
+        return client.request("POST", "api/messages/" + id + "/reply", messageReplyOptions).parseAs(Message.class);
+    }
+
+    /**
+     * Generates screenshots of an email rendered in the specified email clients.
+     *
+     * @param id The identifier of the email to preview.
+     * @param options The options with which to generate previews.
+     * @throws MailosaurException Thrown if Mailosaur responds with an error.
+     * @throws IOException Unexpected exception.
+     * @return the PreviewListResult object if successful.
+     */
+    public PreviewListResult generatePreviews(String id, PreviewRequestOptions options) throws IOException, MailosaurException {
+        return client.request("POST", "api/messages/" + id + "/previews", options).parseAs(PreviewListResult.class);
     }
 
 }

src/main/java/com/mailosaur/Previews.java

@@ -0,0 +1,24 @@
+package com.mailosaur;
+
+import com.mailosaur.models.PreviewEmailClientListResult;
+
+import java.io.IOException;
+
+public class Previews {
+    private MailosaurClient client;
+
+    public Previews(MailosaurClient client) {
+        this.client = client;
+    }
+
+    /**
+     * Returns the list of all email clients that can be used to generate email previews.
+     *
+     * @throws MailosaurException Thrown if Mailosaur responds with an error.
+     * @throws IOException Unexpected exception.
+     * @return The result of the email client listing operation.
+     */
+    public PreviewEmailClientListResult listEmailClients() throws IOException, MailosaurException {
+        return client.request("GET", "api/previews/clients").parseAs(PreviewEmailClientListResult.class);
+    }
+}

src/main/java/com/mailosaur/models/Preview.java

@@ -0,0 +1,53 @@
+package com.mailosaur.models;
+
+import com.google.api.client.util.Key;
+
+/**
+ * Describes an email preview.
+ */
+public class Preview {
+    /**
+     * Unique identifier for the email preview.
+     */
+	@Key
+    private String id;
+
+    /**
+     * The email client the preview was generated with.
+     */
+    @Key
+    private String emailClient;
+
+    /**
+     * True if images were disabled in the preview.
+     */
+    @Key
+    private Boolean disableImages;
+
+    /**
+     * Gets the unique identifier for the email preview.
+     *
+     * @return The unique identifier for the email preview.
+     */
+    public String id() {
+        return this.id;
+    }
+
+    /**
+     * Gets the email client the preview was generated with.
+     *
+     * @return The email client the preview was generated with.
+     */
+    public String emailClient() {
+        return this.emailClient;
+    }
+
+    /**
+     * True if images were disabled in the preview.
+     *
+     * @return True if images were disabled in the preview.
+     */
+    public Boolean disableImages() {
+        return this.disableImages;
+    }
+}

src/main/java/com/mailosaur/models/PreviewEmailClient.java

@@ -0,0 +1,113 @@
+package com.mailosaur.models;
+
+import com.google.api.client.util.Key;
+
+/**
+ * Describes an email client with which email previews can be generated.
+ */
+public class PreviewEmailClient {
+    /**
+     * The unique identifier of the email client.
+     */
+	@Key
+    private String id;
+
+    /**
+     * The display name of the email client.
+     */
+    @Key
+    private String name;
+
+    /**
+     * Whether the platform is desktop, mobile, or web-based.
+     */
+    @Key
+    private String platformGroup;
+
+    /**
+     * The type of platform on which the email client is running.
+     */
+    @Key
+    private String platformType;
+
+    /**
+     * The platform version number.
+     */
+    @Key
+    private String platformVersion;
+
+    /**
+     * If true, images can be disabled when generating previews.
+     */
+    @Key
+    private Boolean canDisableImages;
+
+    /**
+     * The current status of the email client.
+     */
+    @Key
+    private String status;
+
+    /**
+     * Gets the unique identifier of the email client.
+     *
+     * @return The unique identifier of the email client.
+     */
+    public String id() {
+        return this.id;
+    }
+
+    /**
+     * Gets the display name of the email client.
+     *
+     * @return The display name of the email client.
+     */
+    public String name() {
+        return this.name;
+    }
+
+    /**
+     * Gets whether the platform is desktop, mobile, or web-based.
+     *
+     * @return Whether the platform is desktop, mobile, or web-based.
+     */
+    public String platformGroup() {
+        return this.platformGroup;
+    }
+
+    /**
+     * Gets the type of platform on which the email client is running.
+     *
+     * @return The type of platform on which the email client is running.
+     */
+    public String platformType() {
+        return this.platformType;
+    }
+
+    /**
+     * Gets the platform version number.
+     *
+     * @return The platform version number.
+     */
+    public String platformVersion() {
+        return this.platformVersion;
+    }
+
+    /**
+     * If true, images can be disabled when generating previews.
+     *
+     * @return If true, images can be disabled when generating previews.
+     */
+    public Boolean canDisableImages() {
+        return this.canDisableImages;
+    }
+
+    /**
+     * Gets the current status of the email client.
+     *
+     * @return The current status of the email client.
+     */
+    public String status() {
+        return this.status;
+    }
+}

src/main/java/com/mailosaur/models/PreviewEmailClientListResult.java

@@ -0,0 +1,25 @@
+package com.mailosaur.models;
+
+import com.google.api.client.util.Key;
+
+import java.util.List;
+
+/**
+ * A list of available email clients with which to generate email previews.
+ */
+public class PreviewEmailClientListResult {
+    /**
+     * A list of available email clients with which to generate email previews.
+     */
+    @Key
+    private List<PreviewEmailClient> items;
+
+    /**
+     * Gets a list of available email clients.
+     *
+     * @return A list of available email clients.
+     */
+    public List<PreviewEmailClient> items() {
+        return this.items;
+    }
+}

src/main/java/com/mailosaur/models/PreviewListResult.java

@@ -0,0 +1,25 @@
+package com.mailosaur.models;
+
+import com.google.api.client.util.Key;
+
+import java.util.List;
+
+/**
+ * The result of a preview listing operation.
+ */
+public class PreviewListResult {
+    /**
+     * A list of requested email previews.
+     */
+    @Key
+    private List<Preview> items;
+
+    /**
+     * Gets a list of requested email previews.
+     *
+     * @return A list of requested email previews.
+     */
+    public List<Preview> items() {
+        return this.items;
+    }
+}

src/main/java/com/mailosaur/models/PreviewRequest.java

@@ -0,0 +1,52 @@
+package com.mailosaur.models;
+
+import com.google.api.client.util.Key;
+
+/**
+ * Describes an email preview request.
+ */
+public class PreviewRequest {
+    /**
+     * The email client you wish to generate a preview for.
+     */
+    @Key
+    private String emailClient;
+
+    /**
+     * If true, images will be disabled (only if supported by the client).
+     */
+    @Key
+    private Boolean disableImages;
+
+    public PreviewRequest(String emailClient) {
+        this.emailClient = emailClient;
+        this.disableImages = false;
+    }
+
+    public PreviewRequest(String emailClient, Boolean disableImages) {
+        this.emailClient = emailClient;
+        this.disableImages = disableImages;
+    }
+
+    /**
+     * Sets the email client you wish to generate a preview for.
+     *
+     * @param emailClient The email client you wish to generate a preview for.
+     * @return the PreviewRequest object itself.
+     */
+    public PreviewRequest withEmailClient(String emailClient) {
+        this.emailClient = emailClient;
+        return this;
+    }
+
+    /**
+     * Sets whether images should be disabled in the preview (only if supported by the client).
+     *
+     * @param disableImages If true, images will be disabled (only if supported by the client).
+     * @return the PreviewRequest object itself.
+     */
+    public PreviewRequest withDisableImages(Boolean disableImages) {
+        this.disableImages = disableImages;
+        return this;
+    }
+}