Skip to content

feat(receiving): filter listed received emails by recipient and date - #1202

Open
isabellaaquino wants to merge 1 commit into
mainfrom
feature/mes-2800-list-received-emails-filters
Open

isabellaaquino wants to merge 1 commit into
mainfrom
feature/mes-2800-list-received-emails-filters

Conversation

@isabellaaquino

@isabellaaquino isabellaaquino commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Adds the to, startDate and endDate filters from GET /emails/receiving to resend.emails.receiving.list(), so users can list the emails an address received without going through threads.

await resend.emails.receiving.list({
  to: ['support@acme.com'], // up to 20, exact case-sensitive match
  startDate: '2026-11-01',
  endDate: '2026-11-15',
});
  • Option names and shape match inboxes.threads.search (to: string[], camelCase dates), and the URL is built with the same buildInboxCursorUrl helper, which joins to into one comma-separated param as the API expects (repeating to returns a 422).
  • Pagination (limit / after / before) is unchanged.

API: resend/resend-monorepo#13763 (filters, behind the api-filtering team flag) and resend/resend-monorepo#14432 (index-backed to match). Until the flag is on for a team, the API ignores these params.

Linear: MES-2800


Summary by cubic

Adds to, startDate, and endDate filters to resend.emails.receiving.list() so users can list the emails an address received without going through threads.

  • Option names and shape match inboxes.threads.search (to: string[], camelCase dates).
  • The URL is built with the same buildInboxCursorUrl helper, which joins to into one comma-separated param as the API expects; repeating to returns a 422.
  • Pagination (limit, after, before) is unchanged.
  • The API ignores these params until the api-filtering team flag is enabled.

Written for commit 614a1ae. Summary will update on new commits.

View guided diff

@isabellaaquino
isabellaaquino requested a review from a team as a code owner November 16, 2026 20:40
@isabellaaquino
isabellaaquino requested review from klotty and removed request for a team November 16, 2026 20:40
@pkg-pr-new

pkg-pr-new Bot commented Nov 16, 2026

Copy link
Copy Markdown

Open in StackBlitz

npm i https://pkg.pr.new/resend@1202

commit: 614a1ae

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

2 issues found across 3 files

Confidence score: 4/5

  • In list-receiving-emails.interface.ts, an empty to array can be serialized as a bare to= parameter. Skip it in receiving.list or document that to must be non-empty.
  • In receiving.ts, callers may assume to, startDate, and endDate are applied even when the team lacks api-filtering. Document this requirement in the options’ JSDoc.
Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/emails/receiving/interfaces/list-receiving-emails.interface.ts">

<violation number="1" location="src/emails/receiving/interfaces/list-receiving-emails.interface.ts:7">
P2: An empty `to` array is serialized as a bare `to=` parameter instead of being omitted. Either skip the param when the array is empty in `receiving.list`, or document that `to` must be non-empty.</violation>
</file>

<file name="src/emails/receiving/receiving.ts">

<violation number="1" location="src/emails/receiving/receiving.ts:59">
P2: For teams without `api-filtering`, the API does not apply `to`, `startDate`, or `endDate`, and the SDK gives no signal. Document this requirement in the JSDoc for these three options so callers do not assume the filters work.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

export type ListReceivingEmailsOptions = PaginationOptions;
export type ListReceivingEmailsOptions = PaginationOptions & {
/** Only return emails received by one of these addresses (exact, case-sensitive match, up to 20). */
to?: string[];

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: An empty to array is serialized as a bare to= parameter instead of being omitted. Either skip the param when the array is empty in receiving.list, or document that to must be non-empty.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At src/emails/receiving/interfaces/list-receiving-emails.interface.ts, line 7:

<comment>An empty `to` array is serialized as a bare `to=` parameter instead of being omitted. Either skip the param when the array is empty in `receiving.list`, or document that `to` must be non-empty.</comment>

<file context>
@@ -2,7 +2,14 @@ import type { PaginationOptions } from '../../../common/interfaces';
-export type ListReceivingEmailsOptions = PaginationOptions;
+export type ListReceivingEmailsOptions = PaginationOptions & {
+  /** Only return emails received by one of these addresses (exact, case-sensitive match, up to 20). */
+  to?: string[];
+  /** Inclusive lower bound on `created_at`. ISO 8601 date or datetime, read as UTC without an offset. */
+  startDate?: string;
</file context>

requestOptions: RequestOptions = {},
): Promise<ListReceivingEmailsResponse> {
const url = buildPaginationUrl('/emails/receiving', options);
const { to, startDate, endDate, limit } = options;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: For teams without api-filtering, the API does not apply to, startDate, or endDate, and the SDK gives no signal. Document this requirement in the JSDoc for these three options so callers do not assume the filters work.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At src/emails/receiving/receiving.ts, line 59:

<comment>For teams without `api-filtering`, the API does not apply `to`, `startDate`, or `endDate`, and the SDK gives no signal. Document this requirement in the JSDoc for these three options so callers do not assume the filters work.</comment>

<file context>
@@ -56,7 +56,15 @@ export class Receiving {
     requestOptions: RequestOptions = {},
   ): Promise<ListReceivingEmailsResponse> {
-    const url = buildPaginationUrl('/emails/receiving', options);
+    const { to, startDate, endDate, limit } = options;
+    const url = buildInboxCursorUrl('/emails/receiving', {
+      to,
</file context>

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant