feat: contacts list segment

src/main/java/com/resend/services/contacts/Contacts.java

@@ -149,6 +149,58 @@ public ListContactsResponseSuccess list(String segmentId, ListParams params) thr
         return resendMapper.readValue(responseBody, ListContactsResponseSuccess.class);
     }
 
+    /**
+     * Retrieves a list of contacts, optionally scoped to a segment.
+     *
+     * <p>If {@code options} contains a {@code segmentId} (or the deprecated {@code audienceId}),
+     * the contacts are fetched from that segment. When both are provided, {@code segmentId}
+     * takes precedence. If neither is set, all global contacts are returned.</p>
+     *
+     * @param options The options specifying an optional segment/audience ID.
+     * @return A ListContactsResponseSuccess containing the list of contacts.
+     * @throws ResendException If an error occurs during the contacts list retrieval process.
+     */
+    public ListContactsResponseSuccess list(ListContactsOptions options) throws ResendException {
+        String resolvedId = options != null ? options.resolvedSegmentId() : null;
+        String path = resolvedId != null ? "/segments/" + resolvedId + "/contacts" : "/contacts";
+        AbstractHttpResponse<String> response = this.httpClient.perform(path, super.apiKey, HttpMethod.GET, null, MediaType.get("application/json"));
+
+        if (!response.isSuccessful()) {
+            throw new ResendException(response.getCode(), response.getBody());
+        }
+
+        String responseBody = response.getBody();
+
+        return resendMapper.readValue(responseBody, ListContactsResponseSuccess.class);
+    }
+
+    /**
+     * Retrieves a paginated list of contacts, optionally scoped to a segment.
+     *
+     * <p>If {@code options} contains a {@code segmentId} (or the deprecated {@code audienceId}),
+     * the contacts are fetched from that segment. When both are provided, {@code segmentId}
+     * takes precedence. If neither is set, all global contacts are returned.</p>
+     *
+     * @param options The options specifying an optional segment/audience ID.
+     * @param params  The params used to customize the list.
+     * @return A ListContactsResponseSuccess containing the paginated list of contacts.
+     * @throws ResendException If an error occurs during the contacts list retrieval process.
+     */
+    public ListContactsResponseSuccess list(ListContactsOptions options, ListParams params) throws ResendException {
+        String resolvedId = options != null ? options.resolvedSegmentId() : null;
+        String basePath = resolvedId != null ? "/segments/" + resolvedId + "/contacts" : "/contacts";
+        String pathWithQuery = basePath + URLHelper.parse(params);
+        AbstractHttpResponse<String> response = this.httpClient.perform(pathWithQuery, super.apiKey, HttpMethod.GET, null, MediaType.get("application/json"));
+
+        if (!response.isSuccessful()) {
+            throw new ResendException(response.getCode(), response.getBody());
+        }
+
+        String responseBody = response.getBody();
+
+        return resendMapper.readValue(responseBody, ListContactsResponseSuccess.class);
+    }
+
     /**
      * Retrieves a list of global contacts (not associated with any segment).
      *

src/main/java/com/resend/services/contacts/model/ListContactsOptions.java

@@ -0,0 +1,105 @@
+package com.resend.services.contacts.model;
+
+/**
+ * Options for listing contacts, optionally scoped to a segment.
+ *
+ * <p>To list contacts within a segment, provide either {@code segmentId} or the deprecated
+ * {@code audienceId}. When both are provided, {@code segmentId} takes precedence.</p>
+ *
+ * <p>If neither is provided, all global contacts are listed.</p>
+ */
+public class ListContactsOptions {
+
+    private final String segmentId;
+
+    /**
+     * @deprecated Use {@link #segmentId} instead. Kept for backward compatibility.
+     */
+    @Deprecated
+    private final String audienceId;
+
+    private ListContactsOptions(Builder builder) {
+        this.segmentId = builder.segmentId;
+        this.audienceId = builder.audienceId;
+    }
+
+    /**
+     * Returns the segment ID, or falls back to {@code audienceId} if {@code segmentId} is not set.
+     *
+     * @return The resolved segment/audience ID, or {@code null} if neither is set.
+     */
+    public String resolvedSegmentId() {
+        return segmentId != null ? segmentId : audienceId;
+    }
+
+    /**
+     * Gets the segment ID.
+     *
+     * @return The segment ID.
+     */
+    public String getSegmentId() {
+        return segmentId;
+    }
+
+    /**
+     * Gets the audience ID.
+     *
+     * @return The audience ID.
+     * @deprecated Use {@link #getSegmentId()} instead.
+     */
+    @Deprecated
+    public String getAudienceId() {
+        return audienceId;
+    }
+
+    /**
+     * Creates a new builder for {@code ListContactsOptions}.
+     *
+     * @return A new builder instance.
+     */
+    public static Builder builder() {
+        return new Builder();
+    }
+
+    /**
+     * Builder for {@code ListContactsOptions}.
+     */
+    public static class Builder {
+
+        private String segmentId;
+        private String audienceId;
+
+        /**
+         * Sets the segment ID to scope the contact list.
+         *
+         * @param segmentId The segment ID.
+         * @return This builder.
+         */
+        public Builder segmentId(String segmentId) {
+            this.segmentId = segmentId;
+            return this;
+        }
+
+        /**
+         * Sets the audience ID to scope the contact list.
+         *
+         * @param audienceId The audience ID.
+         * @return This builder.
+         * @deprecated Use {@link #segmentId(String)} instead.
+         */
+        @Deprecated
+        public Builder audienceId(String audienceId) {
+            this.audienceId = audienceId;
+            return this;
+        }
+
+        /**
+         * Builds a new {@code ListContactsOptions} instance.
+         *
+         * @return A new {@code ListContactsOptions}.
+         */
+        public ListContactsOptions build() {
+            return new ListContactsOptions(this);
+        }
+    }
+}

src/test/java/com/resend/services/contacts/ContactsTest.java

@@ -56,6 +56,78 @@ public void testRemoveContact_Success() throws ResendException {
         assertEquals(removed, res);
     }
 
+    @Test
+    public void testListContactsBySegmentId_Success() throws ResendException {
+        ListContactsOptions options = ListContactsOptions.builder()
+                .segmentId("segment-123")
+                .build();
+        ListContactsResponseSuccess expectedResponse = ContactsUtil.createContactsListResponse();
+
+        when(contacts.list(options)).thenReturn(expectedResponse);
+
+        ListContactsResponseSuccess res = contacts.list(options);
+
+        assertNotNull(res);
+        assertEquals(expectedResponse.getData().size(), res.getData().size());
+        assertEquals(expectedResponse.getObject(), res.getObject());
+    }
+
+    @Test
+    public void testListContactsByAudienceId_Success() throws ResendException {
+        ListContactsOptions options = ListContactsOptions.builder()
+                .audienceId("audience-123")
+                .build();
+        ListContactsResponseSuccess expectedResponse = ContactsUtil.createContactsListResponse();
+
+        when(contacts.list(options)).thenReturn(expectedResponse);
+
+        ListContactsResponseSuccess res = contacts.list(options);
+
+        assertNotNull(res);
+        assertEquals(expectedResponse.getData().size(), res.getData().size());
+        assertEquals(expectedResponse.getObject(), res.getObject());
+    }
+
+    @Test
+    public void testListContactsSegmentIdTakesPrecedenceOverAudienceId_Success() {
+        ListContactsOptions options = ListContactsOptions.builder()
+                .segmentId("segment-123")
+                .audienceId("audience-456")
+                .build();
+
+        assertEquals("segment-123", options.resolvedSegmentId());
+    }
+
+    @Test
+    public void testListContactsWithPaginationBySegmentId_Success() throws ResendException {
+        ListParams params = ListParams.builder().limit(3).build();
+        ListContactsOptions options = ListContactsOptions.builder()
+                .segmentId("segment-123")
+                .build();
+        ListContactsResponseSuccess expectedResponse = ContactsUtil.createContactsListResponse();
+
+        when(contacts.list(options, params)).thenReturn(expectedResponse);
+
+        ListContactsResponseSuccess res = contacts.list(options, params);
+
+        assertNotNull(res);
+        assertEquals(params.getLimit(), res.getData().size());
+        assertEquals(expectedResponse.getObject(), res.getObject());
+    }
+
+    @Test
+    public void testListContactsGlobalWhenNoId_Success() throws ResendException {
+        ListContactsOptions options = ListContactsOptions.builder().build();
+        ListContactsResponseSuccess expectedResponse = ContactsUtil.createContactsListResponse();
+
+        when(contacts.list(options)).thenReturn(expectedResponse);
+
+        ListContactsResponseSuccess res = contacts.list(options);
+
+        assertNotNull(res);
+        assertEquals(expectedResponse.getData().size(), res.getData().size());
+    }
+
     @Test
     public void testListContacts_Success() throws ResendException {
         String audienceId = "123";