TW-6413: fix for attendees and similar serialization as query params

Author: googsvg

CHANGELOG.md

@@ -5,6 +5,11 @@
 ### Added
 * Optional `TrackingOptions.domainName` support for custom link and open tracking hostnames in regular sends, Transactional Send, drafts, and scheduled sends. The field serializes as `tracking_options.domain_name` and is omitted when unset.
 
+### Fixed
+* `metadata_pair` (calendars, events, messages) is now sent as a single `key:value` query parameter using the first map entry, instead of one repeated parameter per entry. The API accepts exactly one pair, so maps with more than one entry previously had all but one entry silently ignored. Public types are unchanged (`Map<String, String>`); single-entry and empty maps produce the same request as before.
+* `to`, `from`, `cc`, `bcc`, and `in` (messages, threads, drafts) are now sent as a single query parameter using the first list entry, instead of as repeated parameters. The API binds each as a scalar string and validates `to`/`from`/`cc`/`bcc` as one email address, so repeated parameters meant the API silently kept just one value — whichever its parser happened to keep last. Sending one parameter makes that deterministic and matches the behavior `inFolder` already documented. Public types are unchanged (`List<String>`); passing a single-element list produces the same request as before. These parameters will change type to `String` in a future major version.
+* `attendees` (events) and `any_email` (messages, threads, drafts) are now sent as a single comma-delimited query parameter instead of repeated parameters. The API parses both as comma-delimited strings, so passing more than one value previously caused the API to keep only the last one, returning silently incorrect, order-dependent results. Public types are unchanged (`List<String>`), and null, empty, and single-element values produce the same request as before. Note that `any_email` accepts at most 25 addresses; over-long lists now surface an API validation error instead of silently filtering on a single address. `event_type` is unaffected — the API genuinely supports repeating it.
+
 ## [v2.18.0] - Release 2026-07-10
 
 ### Added

src/main/kotlin/com/nylas/NylasClient.kt

@@ -656,14 +656,16 @@ open class NylasClient(
     for ((key, value) in params) {
       when (value) {
         is List<*> -> {
+          // Parameters the API does not accept as repeated values are already collapsed by
+          // the query parameter class itself, via IQueryParams.convertToMap.
           for (item in value) {
             url.addQueryParameter(key, item.toString())
           }
         }
         is Map<*, *> -> {
-          for ((k, v) in value) {
-            url.addQueryParameter(key, "$k:$v")
-          }
+          // Only metadata_pair is a map, and the API accepts exactly one `key:value` pair —
+          // repeating the parameter makes it keep just one and silently ignore the rest.
+          value.entries.firstOrNull()?.let { (k, v) -> url.addQueryParameter(key, "$k:$v") }
         }
         is Double -> {
           url.addQueryParameter(key, value.toInt().toString())

src/main/kotlin/com/nylas/models/IQueryParams.kt

@@ -22,3 +22,48 @@ interface IQueryParams {
     return JsonHelper.jsonMapAdapter.fromJson(json)!!
   }
 }
+
+/**
+ * Rewrite the named `List` query parameters, which the API does not accept as repeated
+ * parameters. An empty list drops the parameter entirely; values that are not lists, and keys
+ * that are absent, are left untouched.
+ *
+ * Each query parameter class declares its own affected keys, rather than [com.nylas.NylasClient]
+ * holding a central list: parameter names are only meaningful per endpoint, and several of them
+ * (`to`, `from`, `cc`, `bcc`) are also request *body* field names, where repeated values are
+ * correct and collapsing them would silently drop recipients.
+ */
+private fun Map<String, Any>.rewriteListParams(
+  keys: Array<out String>,
+  rewrite: (List<*>) -> String,
+): Map<String, Any> {
+  val rewritten = toMutableMap()
+  for (key in keys) {
+    val value = rewritten[key]
+    if (value is List<*>) {
+      if (value.isEmpty()) {
+        rewritten.remove(key)
+      } else {
+        rewritten[key] = rewrite(value)
+      }
+    }
+  }
+  return rewritten
+}
+
+/**
+ * Join query parameters that the API parses as a single comma-delimited string. Repeating them
+ * would make the API keep only one value and silently drop the rest.
+ */
+internal fun Map<String, Any>.joinCommaDelimitedParams(vararg keys: String): Map<String, Any> =
+  rewriteListParams(keys) { list -> list.joinToString(",") }
+
+/**
+ * Send only the first entry of query parameters that the API accepts as a single value, but which
+ * this SDK still types as `List<String>` for backwards compatibility.
+ *
+ * The API keeps exactly one value for these regardless; sending one parameter makes which value
+ * wins deterministic instead of dependent on the API parser's repeated-parameter behavior.
+ */
+internal fun Map<String, Any>.collapseSingleValueParams(vararg keys: String): Map<String, Any> =
+  rewriteListParams(keys) { list -> list.first().toString() }

src/main/kotlin/com/nylas/models/ListDraftsQueryParams.kt

@@ -25,21 +25,41 @@ data class ListDraftsQueryParams(
   val subject: String? = null,
   /**
    * Return emails that have been sent or received from this list of email addresses.
+   * Pass one email address per list entry; the SDK sends them to the API as a single
+   * comma-delimited value. The API accepts a maximum of 25 addresses.
    */
   @Json(name = "any_email")
   val anyEmail: List<String>? = null,
   /**
    * Return items containing drafts to be sent these email address.
+   *
+   * Note: the API filters on a single address. If a list is provided, only the first
+   * entry is used.
+   *
+   * @deprecated The List<String> type for this parameter is deprecated and will be changed to
+   * String in a future major version.
    */
   @Json(name = "to")
   val to: List<String>? = null,
   /**
    * Return items containing drafts cc'ing these email address.
+   *
+   * Note: the API filters on a single address. If a list is provided, only the first
+   * entry is used.
+   *
+   * @deprecated The List<String> type for this parameter is deprecated and will be changed to
+   * String in a future major version.
    */
   @Json(name = "cc")
   val cc: List<String>? = null,
   /**
    * Return items containing drafts bcc'ing these email address.
+   *
+   * Note: the API filters on a single address. If a list is provided, only the first
+   * entry is used.
+   *
+   * @deprecated The List<String> type for this parameter is deprecated and will be changed to
+   * String in a future major version.
    */
   @Json(name = "bcc")
   val bcc: List<String>? = null,
@@ -64,6 +84,16 @@ data class ListDraftsQueryParams(
   @Json(name = "has_attachment")
   val hasAttachment: Boolean? = null,
 ) : IQueryParams {
+
+  /**
+   * The API does not accept repeated values for these parameters.
+   * See [joinCommaDelimitedParams] and [collapseSingleValueParams].
+   */
+  override fun convertToMap(): Map<String, Any> =
+    super.convertToMap()
+      .collapseSingleValueParams("to", "cc", "bcc")
+      .joinCommaDelimitedParams("any_email")
+
   /**
    * Builder for [ListDraftsQueryParams].
    */

src/main/kotlin/com/nylas/models/ListEventQueryParams.kt

@@ -112,7 +112,10 @@ data class ListEventQueryParams(
   val updatedAfter: Long? = null,
   /**
    * Filter for events that include the specified attendees.
-   * This parameter accepts a comma-delimited list of email addresses.
+   * Pass one email address per list entry; the SDK sends them to the API as a single
+   * comma-delimited value.
+   * Note: multiple attendees are matched with AND — an event must include every address
+   * listed to be returned.
    * (Not supported for virtual calendars)
    */
   @Json(name = "attendees")
@@ -135,6 +138,14 @@ data class ListEventQueryParams(
   @Json(name = "tentative_as_busy")
   val tentativeAsBusy: Boolean? = null,
 ) : IQueryParams {
+
+  /**
+   * The API does not accept repeated values for this parameter.
+   * See [joinCommaDelimitedParams].
+   */
+  override fun convertToMap(): Map<String, Any> =
+    super.convertToMap().joinCommaDelimitedParams("attendees")
+
   /**
    * Builder for [ListEventQueryParams].
    */
@@ -295,7 +306,10 @@ data class ListEventQueryParams(
 
     /**
      * Sets the attendees to filter for events with.
-     * This parameter accepts a comma-delimited list of email addresses.
+     * Pass one email address per list entry; the SDK sends them to the API as a single
+     * comma-delimited value.
+     * Note: multiple attendees are matched with AND — an event must include every address
+     * listed to be returned.
      * (Not supported for virtual calendars)
      * @param attendees The attendees to filter for events with.
      * @return The builder.

src/main/kotlin/com/nylas/models/ListMessagesQueryParams.kt

@@ -25,31 +25,63 @@ data class ListMessagesQueryParams(
   val subject: String? = null,
   /**
    * Return emails that have been sent or received from this list of email addresses.
+   * Pass one email address per list entry; the SDK sends them to the API as a single
+   * comma-delimited value. The API accepts a maximum of 25 addresses.
    */
   @Json(name = "any_email")
   val anyEmail: List<String>? = null,
   /**
    * Return items containing messages sent to these email address.
+   *
+   * Note: the API filters on a single address. If a list is provided, only the first
+   * entry is used.
+   *
+   * @deprecated The List<String> type for this parameter is deprecated and will be changed to
+   * String in a future major version.
    */
   @Json(name = "to")
   val to: List<String>? = null,
   /**
    * Return items containing messages sent from these email address.
+   *
+   * Note: the API filters on a single address. If a list is provided, only the first
+   * entry is used.
+   *
+   * @deprecated The List<String> type for this parameter is deprecated and will be changed to
+   * String in a future major version.
    */
   @Json(name = "from")
   val from: List<String>? = null,
   /**
    * Return items containing messages cc'd on these email address.
+   *
+   * Note: the API filters on a single address. If a list is provided, only the first
+   * entry is used.
+   *
+   * @deprecated The List<String> type for this parameter is deprecated and will be changed to
+   * String in a future major version.
    */
   @Json(name = "cc")
   val cc: List<String>? = null,
   /**
    * Return items containing messages bcc'd on these email address.
+   *
+   * Note: the API filters on a single address. If a list is provided, only the first
+   * entry is used.
+   *
+   * @deprecated The List<String> type for this parameter is deprecated and will be changed to
+   * String in a future major version.
    */
   @Json(name = "bcc")
   val bcc: List<String>? = null,
   /**
    * Return emails that are in these folder IDs.
+   *
+   * Note: the API filters on a single folder or label ID. If a list is provided, only the first
+   * entry is used.
+   *
+   * @deprecated The List<String> type for this parameter is deprecated and will be changed to
+   * String in a future major version.
    */
   @Json(name = "in")
   val inFolder: List<String>? = null,
@@ -100,6 +132,16 @@ data class ListMessagesQueryParams(
   @Json(name = "metadata_pair")
   val metadataPair: Map<String, String>? = null,
 ) : IQueryParams {
+
+  /**
+   * The API does not accept repeated values for these parameters.
+   * See [joinCommaDelimitedParams] and [collapseSingleValueParams].
+   */
+  override fun convertToMap(): Map<String, Any> =
+    super.convertToMap()
+      .collapseSingleValueParams("to", "from", "cc", "bcc", "in")
+      .joinCommaDelimitedParams("any_email")
+
   class Builder {
     private var limit: Int? = null
     private var pageToken: String? = null

src/main/kotlin/com/nylas/models/ListThreadsQueryParams.kt

@@ -22,26 +22,52 @@ data class ListThreadsQueryParams(
   val subject: String? = null,
   /**
    * Return emails that have been sent or received from this list of email addresses.
+   * Pass one email address per list entry; the SDK sends them to the API as a single
+   * comma-delimited value. The API accepts a maximum of 25 addresses.
    */
   @Json(name = "any_email")
   val anyEmail: List<String>? = null,
   /**
    * Return items containing messages sent to these email address.
+   *
+   * Note: the API filters on a single address. If a list is provided, only the first
+   * entry is used.
+   *
+   * @deprecated The List<String> type for this parameter is deprecated and will be changed to
+   * String in a future major version.
    */
   @Json(name = "to")
   val to: List<String>? = null,
   /**
    * Return items containing messages sent from these email address.
+   *
+   * Note: the API filters on a single address. If a list is provided, only the first
+   * entry is used.
+   *
+   * @deprecated The List<String> type for this parameter is deprecated and will be changed to
+   * String in a future major version.
    */
   @Json(name = "from")
   val from: List<String>? = null,
   /**
    * Return items containing messages cc'd on these email address.
+   *
+   * Note: the API filters on a single address. If a list is provided, only the first
+   * entry is used.
+   *
+   * @deprecated The List<String> type for this parameter is deprecated and will be changed to
+   * String in a future major version.
    */
   @Json(name = "cc")
   val cc: List<String>? = null,
   /**
    * Return items containing messages bcc'd on these email address.
+   *
+   * Note: the API filters on a single address. If a list is provided, only the first
+   * entry is used.
+   *
+   * @deprecated The List<String> type for this parameter is deprecated and will be changed to
+   * String in a future major version.
    */
   @Json(name = "bcc")
   val bcc: List<String>? = null,
@@ -91,22 +117,13 @@ data class ListThreadsQueryParams(
 ) : IQueryParams {
 
   /**
-   * Override convertToMap to handle the inFolder parameter correctly.
-   * The API expects a single folder ID, so we use only the first item if a list is provided.
+   * The API does not accept repeated values for these parameters.
+   * See [joinCommaDelimitedParams] and [collapseSingleValueParams].
    */
-  override fun convertToMap(): Map<String, Any> {
-    val map = super.convertToMap().toMutableMap()
-
-    // Handle inFolder parameter to use only the first item if it's a list
-    if (inFolder?.isNotEmpty() == true) {
-      map["in"] = inFolder.first()
-    } else if (inFolder?.isEmpty() == true) {
-      // Remove the "in" key if the list is empty
-      map.remove("in")
-    }
-
-    return map
-  }
+  override fun convertToMap(): Map<String, Any> =
+    super.convertToMap()
+      .collapseSingleValueParams("to", "from", "cc", "bcc", "in")
+      .joinCommaDelimitedParams("any_email")
 
   /**
    * Builder for [ListThreadsQueryParams].