Merge pull request #23 from railsware/feature/contacts-update-endpoint

Implemented update contact PATCH endpoint

Author: vitalii-t

.gitignore

@@ -35,4 +35,4 @@ build/
 .vscode/
 
 ### Mac OS ###
-.DS_Store
+.DS_Store

LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2024 Railsware Products Studio LLC
+Copyright (c) 2025 Railsware Products Studio LLC
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -8,33 +8,31 @@ Quickly add email sending functionality to your Java application with Mailtrap.
 
 ## Java Version
 
-Requires JDK 11 or higher
+Requires JDK 11 or higher.
 
-## Usage
-
-### Dependency
+## Install package
 
-Maven dependency
+As Maven dependency:
 
 ```xml
 
 <dependency>
     <groupId>io.mailtrap</groupId>
     <artifactId>mailtrap-java</artifactId>
-    <version>0.0.1</version>
+    <version>1.0.0</version>
 </dependency>
 ```
 
-Gradle Groovy dependency
+As Gradle Groovy dependency:
 
 ```groovy
-implementation 'io.mailtrap:mailtrap-java:0.0.1'
+implementation 'io.mailtrap:mailtrap-java:1.0.0'
 ```
 
-Gradle Kotlin DSL dependency
+As Gradle Kotlin DSL dependency:
 
 ```kotlin
-implementation("io.mailtrap:mailtrap-java:0.0.1")
+implementation("io.mailtrap:mailtrap-java:1.0.0")
 ```
 
 ## Usage
@@ -72,14 +70,14 @@ public class MailtrapJavaSDKTest {
                 .text("Welcome to Mailtrap Sending!")
                 .build();
 
+        // Send email using Mailtrap Sending API
         try {
             System.out.println(client.send(mail));
         } catch (Exception e) {
             System.out.println("Caught exception : " + e);
         }
 
-        // OR send email to the Mailtrap Sandbox
-
+        // Or send email using Mailtrap Testing API
         try {
             long inboxId = 1000001L;
 
@@ -98,7 +96,7 @@ public class MailtrapJavaSDKTest {
 
             System.out.println(client.send(mail));
 
-            // Or use directly Testing API to send email to Sandbox
+            // Or use Testing API directly
             System.out.println(client.testingApi().emails().send(mail, inboxId));
         } catch (Exception e) {
             System.out.println("Caught exception : " + e);
@@ -127,18 +125,23 @@ You can find the API reference [here](https://railsware.github.io/mailtrap-java/
 - [Error handling](examples/java/io/mailtrap/examples/sending/Errors.java)
 - [Send email using template](examples/java/io/mailtrap/examples/sending/Template.java)
 
-### Email testing API
+### Email Testing API
 
 - [Attachments](examples/java/io/mailtrap/examples/testing/Attachments.java)
 - [Inboxes](examples/java/io/mailtrap/examples/testing/Inboxes.java)
 - [Messages](examples/java/io/mailtrap/examples/testing/Messages.java)
 - [Projects](examples/java/io/mailtrap/examples/testing/Projects.java)
 - [Send mail using template](examples/java/io/mailtrap/examples/testing/Email.java)
 
-### Bulk sending API
+### Bulk Sending API
 
 - [Send mail](examples/java/io/mailtrap/examples/bulk/BulkSend.java)
 
+### Contacts API
+
+- [Contacts](examples/java/io/mailtrap/examples/contacts/Contacts.java)
+- [Contact lists](examples/java/io/mailtrap/examples/contact_lists/ContactLists.java)
+
 ## Contributing
 
 Bug reports and pull requests are welcome on [GitHub](https://github.com/railsware/mailtrap-java). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](CODE_OF_CONDUCT.md).

docs/docfx.json

@@ -15,4 +15,4 @@
     ],
     "dest": "_site"
   }
-}
+}

docs/getting-started.md

@@ -4,36 +4,39 @@ Follow these few simple steps to add Mailtrap API functionality into your Java p
 
 # Prerequisites
 
-Make sure your project uses JDK 11 or higher
+Make sure your project uses JDK 11 or higher.
 
 ## Setup
 
 ### 1. Add the library as a Maven/Gradle dependency
-Maven dependency
+
+Maven dependency:
 
 ```xml
 
 <dependency>
     <groupId>io.mailtrap</groupId>
     <artifactId>mailtrap-java</artifactId>
-    <version>*latest-version*</version>
+    <version>1.0.0</version>
 </dependency>
 ```
 
-Gradle Groovy dependency
+Gradle Groovy dependency:
 
 ```groovy
-implementation 'io.mailtrap:mailtrap-java:*latest-version*'
+implementation 'io.mailtrap:mailtrap-java:1.0.0'
 ```
 
-Gradle Kotlin DSL dependency
+Gradle Kotlin DSL dependency:
 
 ```kotlin
-implementation("io.mailtrap:mailtrap-java:*latest-version*")
+implementation("io.mailtrap:mailtrap-java:1.0.0")
 ```
 
-### 2. Register/login into Mailtrap account
-Obtain API token to configure and use MailtrapClient
+### 2. Authentication
+
+- Register/login into Mailtrap
+- Obtain an API token [with respective permissions and access level](https://help.mailtrap.io/article/103-api-tokens) to configure and use MailtrapClient.
 
 ### 3. Configuration and usage
 
@@ -73,4 +76,4 @@ public class Minimal {
         }
     }
 }
-```
+```

docs/index.md

@@ -7,12 +7,12 @@ Welcome to the documentation portal for the official <a href="https://mailtrap.i
 
 This client allows you to quickly and easily integrate your Java application with Mailtrap API.
 
-
 ## Table of contents
 
 - [Getting Started](getting-started.md) - quick overview on how to integrate Mailtrap into your project
 - [Usage Examples](usage-examples.md) 
 - [API Reference](javadocs.md) - Detailed API Reference
 
 ## License
-Licensed under the <a href="https://github.com/railsware/mailtrap-java/blob/main/LICENSE.txt" target="_blank">MIT License</a>.
+
+Licensed under the <a href="https://github.com/railsware/mailtrap-java/blob/main/LICENSE.txt" target="_blank">MIT License</a>.

docs/toc.yml

@@ -5,4 +5,4 @@
 - name: Usage Examples
   href: usage-examples.md
 - name: API Reference
-  href: javadocs.md
+  href: javadocs.md

docs/usage-examples.md

@@ -1,3 +1,3 @@
 # Detailed Usage Examples
 
-Code examples, that covers all possible APIs can be found <a href="https://github.com/railsware/mailtrap-java/tree/main/examples/java/io/mailtrap/examples" target="_blank">here</a>
+Code examples covering all APIs can be found <a href="https://github.com/railsware/mailtrap-java/tree/main/examples/java/io/mailtrap/examples" target="_blank">here</a>.

examples/java/io/mailtrap/examples/contacts/Contacts.java

@@ -2,9 +2,12 @@
 
 import io.mailtrap.config.MailtrapConfig;
 import io.mailtrap.factory.MailtrapClientFactory;
-import io.mailtrap.model.request.contacts.Contact;
+import io.mailtrap.model.request.contacts.CreateContact;
 import io.mailtrap.model.request.contacts.CreateContactRequest;
+import io.mailtrap.model.request.contacts.UpdateContact;
+import io.mailtrap.model.request.contacts.UpdateContactRequest;
 
+import java.util.Collections;
 import java.util.List;
 import java.util.Map;
 
@@ -15,19 +18,31 @@ public class Contacts {
     private static final long LIST_1_ID = 1L;
     private static final long LIST_2_ID = 2L;
     private static final String EMAIL = "[email protected]";
+    private static final boolean UNSUBSCRIBED = false;
 
     public static void main(String[] args) {
         final var config = new MailtrapConfig.Builder()
-                .token(TOKEN)
-                .build();
+            .token(TOKEN)
+            .build();
 
         final var client = MailtrapClientFactory.createMailtrapClient(config);
 
-        var request = new CreateContactRequest(new Contact(EMAIL, Map.of("first_name", "Nick"), List.of(LIST_1_ID, LIST_2_ID)));
+        var createRequest = new CreateContactRequest(
+            new CreateContact(EMAIL, Map.of("first_name", "Nick"), List.of(LIST_1_ID, LIST_2_ID)));
 
-        var response = client.contactsApi().contacts().createContact(ACCOUNT_ID, request);
+        var createResponse = client.contactsApi().contacts()
+            .createContact(ACCOUNT_ID, createRequest);
 
-        System.out.println(response);
+        System.out.println(createResponse);
+
+        var updateRequest = new UpdateContactRequest(
+            new UpdateContact(EMAIL, Map.of("first_name", "Nick"), List.of(LIST_1_ID, LIST_2_ID),
+                Collections.emptyList(), UNSUBSCRIBED));
+
+        var updateResponse = client.contactsApi().contacts()
+            .updateContact(ACCOUNT_ID, EMAIL, updateRequest);
+
+        System.out.println(updateResponse);
 
         client.contactsApi().contacts().deleteContact(ACCOUNT_ID, EMAIL);
     }

pom.xml

@@ -6,7 +6,7 @@
 
     <groupId>io.mailtrap</groupId>
     <artifactId>mailtrap-java</artifactId>
-    <version>0.0.1</version>
+    <version>1.0.0</version>
 
     <name>Mailtrap Java SDK</name>
     <description>The official Mailtrap SDK for Java provides Java APIs
@@ -236,4 +236,4 @@
         </plugins>
     </build>
 
-</project>
+</project>

src/main/java/io/mailtrap/api/contacts/Contacts.java

@@ -1,25 +1,37 @@
 package io.mailtrap.api.contacts;
 
 import io.mailtrap.model.request.contacts.CreateContactRequest;
+import io.mailtrap.model.request.contacts.UpdateContactRequest;
 import io.mailtrap.model.response.contacts.CreateContactResponse;
+import io.mailtrap.model.response.contacts.UpdateContactResponse;
 
 public interface Contacts {
 
-    /**
-     * Create a new contact
-     *
-     * @param accountId unique account ID
-     * @param request   required contact data
-     * @return created contact
-     */
-    CreateContactResponse createContact(long accountId, CreateContactRequest request);
+  /**
+   * Create a new contact
+   *
+   * @param accountId unique account ID
+   * @param request   required contact data
+   * @return created contact
+   */
+  CreateContactResponse createContact(long accountId, CreateContactRequest request);
 
-    /**
-     * Delete contact using id or email (URL encoded)
-     *
-     * @param accountId unique account ID
-     * @param idOrEmail contact ID or Email
-     */
-    void deleteContact(long accountId, String idOrEmail);
+  /**
+   * Delete contact using id or email (URL encoded)
+   *
+   * @param accountId unique account ID
+   * @param idOrEmail contact ID or Email
+   */
+  void deleteContact(long accountId, String idOrEmail);
+
+  /**
+   * Update contact using id or email (URL encoded)
+   *
+   * @param accountId unique account ID
+   * @param idOrEmail contact ID or Email
+   * @param request   request body
+   */
+  UpdateContactResponse updateContact(long accountId, String idOrEmail,
+      UpdateContactRequest request);
 
 }

src/main/java/io/mailtrap/api/contacts/ContactsImpl.java

@@ -5,35 +5,48 @@
 import io.mailtrap.config.MailtrapConfig;
 import io.mailtrap.http.RequestData;
 import io.mailtrap.model.request.contacts.CreateContactRequest;
+import io.mailtrap.model.request.contacts.UpdateContactRequest;
 import io.mailtrap.model.response.contacts.CreateContactResponse;
-
+import io.mailtrap.model.response.contacts.UpdateContactResponse;
 import java.net.URLEncoder;
 import java.nio.charset.Charset;
-import java.util.Base64;
 
 public class ContactsImpl extends ApiResource implements Contacts {
 
-    public ContactsImpl(MailtrapConfig config) {
-        super(config);
-        this.apiHost = Constants.GENERAL_HOST;
-    }
+  public ContactsImpl(MailtrapConfig config) {
+    super(config);
+    this.apiHost = Constants.GENERAL_HOST;
+  }
+
+  @Override
+  public CreateContactResponse createContact(long accountId, CreateContactRequest request) {
+    return httpClient.post(
+        String.format(apiHost + "/api/accounts/%s/contacts", accountId),
+        request,
+        new RequestData(),
+        CreateContactResponse.class
+    );
+  }
 
-    @Override
-    public CreateContactResponse createContact(long accountId, CreateContactRequest request) {
-        return httpClient.post(
-                String.format(apiHost + "/api/accounts/%s/contacts", accountId),
-                request,
-                new RequestData(),
-                CreateContactResponse.class
-        );
-    }
+  @Override
+  public void deleteContact(long accountId, String idOrEmail) {
+    httpClient.delete(
+        String.format(apiHost + "/api/accounts/%s/contacts/%s", accountId,
+            URLEncoder.encode(idOrEmail, Charset.defaultCharset())),
+        new RequestData(),
+        Void.class
+    );
+  }
 
-    @Override
-    public void deleteContact(long accountId, String idOrEmail) {
-        httpClient.delete(
-                String.format(apiHost + "/api/accounts/%s/contacts/%s", accountId, URLEncoder.encode(idOrEmail, Charset.defaultCharset())),
-                new RequestData(),
-                Void.class
-        );
-    }
+  @Override
+  public UpdateContactResponse updateContact(long accountId, String idOrEmail,
+      UpdateContactRequest request) {
+    return httpClient.patch(
+        String.format(apiHost + "/api/accounts/%s/contacts/%s", accountId,
+            URLEncoder.encode(idOrEmail, Charset.defaultCharset())),
+        request,
+        new RequestData(),
+        UpdateContactResponse.class
+    );
+  }
 }