Add Inbound Email API support

README.md

@@ -361,6 +361,13 @@ You can find the [Mailtrap Java API reference](https://mailtrap.github.io/mailtr
 - [Sandbox send using template](examples/java/io/mailtrap/examples/testing/EmailExample.java)
 - [Batch](examples/java/io/mailtrap/examples/testing/BatchExample.java)
 
+### Inbound Email API
+
+- [Folders](examples/java/io/mailtrap/examples/inbound/InboundFoldersExample.java)
+- [Inboxes](examples/java/io/mailtrap/examples/inbound/InboundInboxesExample.java)
+- [Messages](examples/java/io/mailtrap/examples/inbound/InboundMessagesExample.java)
+- [Threads](examples/java/io/mailtrap/examples/inbound/InboundThreadsExample.java)
+
 ### Bulk Sending API
 
 - [Bulk send](examples/java/io/mailtrap/examples/bulk/BulkSendExample.java)

examples/java/io/mailtrap/examples/inbound/InboundFoldersExample.java

@@ -0,0 +1,41 @@
+package io.mailtrap.examples.inbound;
+
+import io.mailtrap.config.MailtrapConfig;
+import io.mailtrap.factory.MailtrapClientFactory;
+import io.mailtrap.model.request.inbound.CreateInboundFolderRequest;
+import io.mailtrap.model.request.inbound.UpdateInboundFolderRequest;
+
+public class InboundFoldersExample {
+
+    private static final String TOKEN = "<YOUR MAILTRAP TOKEN>";
+
+    public static void main(String[] args) {
+        final var config = new MailtrapConfig.Builder()
+                .token(TOKEN)
+                .build();
+
+        final var client = MailtrapClientFactory.createMailtrapClient(config);
+        final var folders = client.inboundApi().folders();
+
+        // List all inbound folders.
+        final var allFolders = folders.getList();
+        System.out.println(allFolders);
+
+        // Create an inbound folder.
+        final var created = folders.create(
+                CreateInboundFolderRequest.builder().name("Support").build());
+        System.out.println(created);
+
+        // Get an inbound folder by ID.
+        final var folder = folders.getById(created.getId());
+        System.out.println(folder);
+
+        // Rename an inbound folder.
+        final var updated = folders.update(created.getId(),
+                UpdateInboundFolderRequest.builder().name("Support (renamed)").build());
+        System.out.println(updated);
+
+        // Delete an inbound folder (removes the folder and all of its inboxes).
+        folders.delete(created.getId());
+    }
+}

examples/java/io/mailtrap/examples/inbound/InboundInboxesExample.java

@@ -0,0 +1,43 @@
+package io.mailtrap.examples.inbound;
+
+import io.mailtrap.config.MailtrapConfig;
+import io.mailtrap.factory.MailtrapClientFactory;
+import io.mailtrap.model.request.inbound.CreateInboundInboxRequest;
+import io.mailtrap.model.request.inbound.UpdateInboundInboxRequest;
+
+public class InboundInboxesExample {
+
+    private static final String TOKEN = "<YOUR MAILTRAP TOKEN>";
+    private static final long FOLDER_ID = 1L;
+
+    public static void main(String[] args) {
+        final var config = new MailtrapConfig.Builder()
+                .token(TOKEN)
+                .build();
+
+        final var client = MailtrapClientFactory.createMailtrapClient(config);
+        final var inboxes = client.inboundApi().inboxes();
+
+        // List inboxes in a folder.
+        final var allInboxes = inboxes.getList(FOLDER_ID);
+        System.out.println(allInboxes);
+
+        // Create a Mailtrap-hosted inbox (omit the domain ID). To create a
+        // custom-domain catch-all inbox, pass .domainId(<verified sending domain id>).
+        final var created = inboxes.create(FOLDER_ID,
+                CreateInboundInboxRequest.builder().name("Support inbox").build());
+        System.out.println(created);
+
+        // Get an inbox by ID.
+        final var inbox = inboxes.getById(FOLDER_ID, created.getId());
+        System.out.println(inbox);
+
+        // Rename an inbox.
+        final var updated = inboxes.update(FOLDER_ID, created.getId(),
+                UpdateInboundInboxRequest.builder().name("Support inbox (renamed)").build());
+        System.out.println(updated);
+
+        // Delete an inbox.
+        inboxes.delete(FOLDER_ID, created.getId());
+    }
+}

examples/java/io/mailtrap/examples/inbound/InboundMessagesExample.java

@@ -0,0 +1,63 @@
+package io.mailtrap.examples.inbound;
+
+import io.mailtrap.config.MailtrapConfig;
+import io.mailtrap.factory.MailtrapClientFactory;
+import io.mailtrap.model.request.emails.Address;
+import io.mailtrap.model.request.inbound.InboundForwardRequest;
+import io.mailtrap.model.request.inbound.InboundReplyRequest;
+
+import java.util.List;
+
+public class InboundMessagesExample {
+
+    private static final String TOKEN = "<YOUR MAILTRAP TOKEN>";
+    private static final long INBOX_ID = 1L;
+
+    public static void main(String[] args) {
+        final var config = new MailtrapConfig.Builder()
+                .token(TOKEN)
+                .build();
+
+        final var client = MailtrapClientFactory.createMailtrapClient(config);
+        final var messages = client.inboundApi().messages();
+
+        // List received messages. Pass the previous page's last id to paginate
+        // (null for the first page).
+        final var page = messages.list(INBOX_ID, null);
+        System.out.println("Total: " + page.getTotalCount());
+        page.getData().forEach(msg -> System.out.println("  " + msg.getId() + " " + msg.getSubject()));
+
+        if (page.getData().isEmpty()) {
+            return;
+        }
+        final var messageId = page.getData().get(0).getId();
+
+        // Get a single message with its body and attachment download URLs.
+        final var message = messages.get(INBOX_ID, messageId);
+        System.out.println(message);
+
+        // Reply to a message (sends a real email to the original sender).
+        final var reply = messages.reply(INBOX_ID, messageId, InboundReplyRequest.builder()
+                .subject("Re: Support request")
+                .text("Thanks for reaching out!")
+                .html("<p>Thanks for reaching out!</p>")
+                .build());
+        System.out.println(reply);
+
+        // Reply to a message and copy the original's other recipients.
+        final var replyAll = messages.replyAll(INBOX_ID, messageId, InboundReplyRequest.builder()
+                .text("Looping everyone in.")
+                .build());
+        System.out.println(replyAll);
+
+        // Forward a message to new recipients (at least one `to` is required).
+        final var forward = messages.forward(INBOX_ID, messageId, InboundForwardRequest.builder()
+                .to(List.of(new Address("colleague@example.com")))
+                .text("Please take a look.")
+                .build());
+        System.out.println(forward);
+
+        // Delete a message.
+        messages.delete(INBOX_ID, messageId);
+    }
+}

examples/java/io/mailtrap/examples/inbound/InboundThreadsExample.java

@@ -0,0 +1,37 @@
+package io.mailtrap.examples.inbound;
+
+import io.mailtrap.config.MailtrapConfig;
+import io.mailtrap.factory.MailtrapClientFactory;
+
+public class InboundThreadsExample {
+
+    private static final String TOKEN = "<YOUR MAILTRAP TOKEN>";
+    private static final long INBOX_ID = 1L;
+
+    public static void main(String[] args) {
+        final var config = new MailtrapConfig.Builder()
+                .token(TOKEN)
+                .build();
+
+        final var client = MailtrapClientFactory.createMailtrapClient(config);
+        final var threads = client.inboundApi().threads();
+
+        // List conversation threads. Pass the previous page's last id to paginate
+        // (null for the first page).
+        final var page = threads.list(INBOX_ID, null);
+        System.out.println("Total: " + page.getTotalCount());
+        page.getData().forEach(thread -> System.out.println("  " + thread.getId() + " " + thread.getSubject()));
+
+        if (page.getData().isEmpty()) {
+            return;
+        }
+        final var threadId = page.getData().get(0).getId();
+
+        // Get a single thread with its messages embedded (oldest first).
+        final var thread = threads.get(INBOX_ID, threadId);
+        System.out.println(thread);
+
+        // Delete a thread.
+        threads.delete(INBOX_ID, threadId);
+    }
+}

src/main/java/io/mailtrap/api/inbound/InboundFolders.java

@@ -0,0 +1,52 @@
+package io.mailtrap.api.inbound;
+
+import io.mailtrap.model.request.inbound.CreateInboundFolderRequest;
+import io.mailtrap.model.request.inbound.UpdateInboundFolderRequest;
+import io.mailtrap.model.response.inbound.InboundFolder;
+
+import java.util.List;
+
+/**
+ * Interface representing the Mailtrap Inbound Email API for managing folders.
+ */
+public interface InboundFolders {
+
+    /**
+     * List all inbound folders in the account.
+     *
+     * @return the list of inbound folders
+     */
+    List<InboundFolder> getList();
+
+    /**
+     * Get an inbound folder by ID.
+     *
+     * @param folderId the folder ID
+     * @return the folder
+     */
+    InboundFolder getById(long folderId);
+
+    /**
+     * Create a new inbound folder.
+     *
+     * @param request the create request
+     * @return the created folder
+     */
+    InboundFolder create(CreateInboundFolderRequest request);
+
+    /**
+     * Rename an inbound folder.
+     *
+     * @param folderId the folder ID
+     * @param request  the update request
+     * @return the updated folder
+     */
+    InboundFolder update(long folderId, UpdateInboundFolderRequest request);
+
+    /**
+     * Delete an inbound folder along with all of its inboxes.
+     *
+     * @param folderId the folder ID
+     */
+    void delete(long folderId);
+}

src/main/java/io/mailtrap/api/inbound/InboundFoldersImpl.java

@@ -0,0 +1,66 @@
+package io.mailtrap.api.inbound;
+
+import io.mailtrap.Constants;
+import io.mailtrap.api.apiresource.ApiResource;
+import io.mailtrap.config.MailtrapConfig;
+import io.mailtrap.http.RequestData;
+import io.mailtrap.model.request.inbound.CreateInboundFolderRequest;
+import io.mailtrap.model.request.inbound.UpdateInboundFolderRequest;
+import io.mailtrap.model.response.inbound.InboundFolder;
+
+import java.util.List;
+
+public class InboundFoldersImpl extends ApiResource implements InboundFolders {
+
+    public InboundFoldersImpl(final MailtrapConfig config) {
+        super(config);
+        this.apiHost = Constants.GENERAL_HOST;
+    }
+
+    @Override
+    public List<InboundFolder> getList() {
+        return httpClient.getList(
+            apiHost + "/api/inbound/folders",
+            new RequestData(),
+            InboundFolder.class
+        );
+    }
+
+    @Override
+    public InboundFolder getById(final long folderId) {
+        return httpClient.get(
+            String.format(apiHost + "/api/inbound/folders/%d", folderId),
+            new RequestData(),
+            InboundFolder.class
+        );
+    }
+
+    @Override
+    public InboundFolder create(final CreateInboundFolderRequest request) {
+        return httpClient.post(
+            apiHost + "/api/inbound/folders",
+            request,
+            new RequestData(),
+            InboundFolder.class
+        );
+    }
+
+    @Override
+    public InboundFolder update(final long folderId, final UpdateInboundFolderRequest request) {
+        return httpClient.patch(
+            String.format(apiHost + "/api/inbound/folders/%d", folderId),
+            request,
+            new RequestData(),
+            InboundFolder.class
+        );
+    }
+
+    @Override
+    public void delete(final long folderId) {
+        httpClient.delete(
+            String.format(apiHost + "/api/inbound/folders/%d", folderId),
+            new RequestData(),
+            Void.class
+        );
+    }
+}

src/main/java/io/mailtrap/api/inbound/InboundInboxes.java

@@ -0,0 +1,58 @@
+package io.mailtrap.api.inbound;
+
+import io.mailtrap.model.request.inbound.CreateInboundInboxRequest;
+import io.mailtrap.model.request.inbound.UpdateInboundInboxRequest;
+import io.mailtrap.model.response.inbound.InboundInbox;
+
+import java.util.List;
+
+/**
+ * Interface representing the Mailtrap Inbound Email API for managing inboxes
+ * within a folder.
+ */
+public interface InboundInboxes {
+
+    /**
+     * List all inboxes in an inbound folder.
+     *
+     * @param folderId the folder ID
+     * @return the list of inboxes
+     */
+    List<InboundInbox> getList(long folderId);
+
+    /**
+     * Get an inbound inbox by ID.
+     *
+     * @param folderId the folder ID
+     * @param inboxId  the inbox ID
+     * @return the inbox
+     */
+    InboundInbox getById(long folderId, long inboxId);
+
+    /**
+     * Create a new inbound inbox in a folder.
+     *
+     * @param folderId the folder ID
+     * @param request  the create request
+     * @return the created inbox
+     */
+    InboundInbox create(long folderId, CreateInboundInboxRequest request);
+
+    /**
+     * Rename an inbound inbox.
+     *
+     * @param folderId the folder ID
+     * @param inboxId  the inbox ID
+     * @param request  the update request
+     * @return the updated inbox
+     */
+    InboundInbox update(long folderId, long inboxId, UpdateInboundInboxRequest request);
+
+    /**
+     * Delete an inbound inbox.
+     *
+     * @param folderId the folder ID
+     * @param inboxId  the inbox ID
+     */
+    void delete(long folderId, long inboxId);
+}