diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 8b433f9..f9ab065 100644 --- a/.github/workflows/build.yml +++ b/.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: diff --git a/pom.xml b/pom.xml index 10ce878..9fbdc92 100644 --- a/pom.xml +++ b/pom.xml @@ -25,7 +25,7 @@ MIT license - https://github.com/mailosaur/mailosaur-java/blob/master/LICENSE + https://github.com/mailosaur/mailosaur-java/blob/main/LICENSE diff --git a/src/main/java/com/mailosaur/Files.java b/src/main/java/com/mailosaur/Files.java index 235f5a5..eb455e5 100644 --- a/src/main/java/com/mailosaur/Files.java +++ b/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(); + } + } diff --git a/src/main/java/com/mailosaur/MailosaurClient.java b/src/main/java/com/mailosaur/MailosaurClient.java index 37f220c..abf6e70 100644 --- a/src/main/java/com/mailosaur/MailosaurClient.java +++ b/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); diff --git a/src/main/java/com/mailosaur/Messages.java b/src/main/java/com/mailosaur/Messages.java index e7f89c5..8eac1c0 100644 --- a/src/main/java/com/mailosaur/Messages.java +++ b/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); } } diff --git a/src/main/java/com/mailosaur/Previews.java b/src/main/java/com/mailosaur/Previews.java new file mode 100644 index 0000000..496d275 --- /dev/null +++ b/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); + } +} diff --git a/src/main/java/com/mailosaur/models/Preview.java b/src/main/java/com/mailosaur/models/Preview.java new file mode 100644 index 0000000..355a562 --- /dev/null +++ b/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; + } +} diff --git a/src/main/java/com/mailosaur/models/PreviewEmailClient.java b/src/main/java/com/mailosaur/models/PreviewEmailClient.java new file mode 100644 index 0000000..a01629d --- /dev/null +++ b/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; + } +} diff --git a/src/main/java/com/mailosaur/models/PreviewEmailClientListResult.java b/src/main/java/com/mailosaur/models/PreviewEmailClientListResult.java new file mode 100644 index 0000000..7985a22 --- /dev/null +++ b/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 items; + + /** + * Gets a list of available email clients. + * + * @return A list of available email clients. + */ + public List items() { + return this.items; + } +} diff --git a/src/main/java/com/mailosaur/models/PreviewListResult.java b/src/main/java/com/mailosaur/models/PreviewListResult.java new file mode 100644 index 0000000..81ec37a --- /dev/null +++ b/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 items; + + /** + * Gets a list of requested email previews. + * + * @return A list of requested email previews. + */ + public List items() { + return this.items; + } +} diff --git a/src/main/java/com/mailosaur/models/PreviewRequest.java b/src/main/java/com/mailosaur/models/PreviewRequest.java new file mode 100644 index 0000000..7380c9e --- /dev/null +++ b/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; + } +} diff --git a/src/main/java/com/mailosaur/models/PreviewRequestOptions.java b/src/main/java/com/mailosaur/models/PreviewRequestOptions.java new file mode 100644 index 0000000..4c8ab31 --- /dev/null +++ b/src/main/java/com/mailosaur/models/PreviewRequestOptions.java @@ -0,0 +1,27 @@ +package com.mailosaur.models; + +import com.google.api.client.util.Key; + +import java.util.List; + +/** + * Preview request options. + */ +public class PreviewRequestOptions { + /** + * The list of email preview requests. + */ + @Key + private List previews; + + /** + * Sets the list of email preview requests. + * + * @param previews The list of email preview requests. + * @return the PreviewRequestOptions object itself. + */ + public PreviewRequestOptions withPreviews(List previews) { + this.previews = previews; + return this; + } +} diff --git a/src/test/java/com/mailosaur/Mailer.java b/src/test/java/com/mailosaur/Mailer.java index 555b19c..b7608c3 100644 --- a/src/test/java/com/mailosaur/Mailer.java +++ b/src/test/java/com/mailosaur/Mailer.java @@ -108,7 +108,7 @@ private static Path getResourceFilePath(String relativePath) { return Paths.get(path); } - private static String getRandomString(int length) { + public static String getRandomString(int length) { int leftLimit = 97; // letter 'a' int rightLimit = 122; // letter 'z' Random random = new Random(); diff --git a/src/test/java/com/mailosaur/PreviewsTests.java b/src/test/java/com/mailosaur/PreviewsTests.java new file mode 100644 index 0000000..504f8d4 --- /dev/null +++ b/src/test/java/com/mailosaur/PreviewsTests.java @@ -0,0 +1,66 @@ +package com.mailosaur; + +import com.mailosaur.models.*; +import org.junit.BeforeClass; +import org.junit.Test; + +import javax.mail.MessagingException; +import java.io.IOException; +import java.util.Arrays; + +import static org.junit.Assert.*; + +public class PreviewsTests { + private static MailosaurClient client; + private static String server; + + @BeforeClass + public static void setUpBeforeClass() throws IOException, InterruptedException, MessagingException, MailosaurException { + String baseUrl = System.getenv("MAILOSAUR_BASE_URL"); + String apiKey = System.getenv("MAILOSAUR_API_KEY"); + server = System.getenv("MAILOSAUR_PREVIEWS_SERVER"); + + if (apiKey == null) { + throw new IOException("Missing necessary environment variables - refer to README.md"); + } + + client = new MailosaurClient(apiKey, baseUrl); + } + + @Test + public void testListEmailClients() throws IOException, MailosaurException { + PreviewEmailClientListResult result = client.previews().listEmailClients(); + assertTrue(result.items().size() > 1); + } + + @Test + public void testGeneratePreviews() throws IOException, MailosaurException, MessagingException { + org.junit.Assume.assumeTrue(server != null && !server.isEmpty()); + + String randomString = Mailer.getRandomString(7); + String host = System.getenv("MAILOSAUR_SMTP_HOST"); + host = (host == null) ? "mailosaur.net" : host; + + String testEmailAddress = String.format("%s@%s.%s", randomString, server, host); + + Mailer.sendEmail(client, server, testEmailAddress); + + SearchCriteria criteria = new SearchCriteria(); + criteria.withSentTo(testEmailAddress); + + MessageSearchParams params = new MessageSearchParams(); + params.withServer(server); + Message email = client.messages().get(params, criteria); + + PreviewRequest request = new PreviewRequest("OL2021"); + PreviewRequestOptions options = new PreviewRequestOptions(); + options.withPreviews(Arrays.asList(request)); + + PreviewListResult result = client.messages().generatePreviews(email.id(), options); + assertTrue(result.items().size() > 0); + + // Ensure we can download one of the generated preview + byte[] bytes = client.files().getPreview(result.items().get(0).id()); + assertNotNull(bytes); + } +} \ No newline at end of file