cloudflare/src/resources/email-security/submissions.ts

The official TypeScript library for the Cloudflare API

// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.

import { APIResource } from '../../core/resource';
import { PagePromise, V4PagePaginationArray, type V4PagePaginationArrayParams } from '../../core/pagination';
import { RequestOptions } from '../../internal/request-options';
import { path } from '../../internal/utils/path';

export class BaseSubmissions extends APIResource {
  static override readonly _key: readonly ['emailSecurity', 'submissions'] = Object.freeze([
    'emailSecurity',
    'submissions',
  ] as const);

  /**
   * Returns information for submissions made to reclassify emails. Shows the status,
   * outcome, and disposition changes for reclassification requests made by users or
   * the security team. Useful for tracking false positive/negative reports.
   *
   * @example
   * ```ts
   * // Automatically fetches more pages as needed.
   * for await (const submissionListResponse of client.emailSecurity.submissions.list(
   *   { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
   * )) {
   *   // ...
   * }
   * ```
   */
  list(
    params: SubmissionListParams,
    options?: RequestOptions,
  ): PagePromise<SubmissionListResponsesV4PagePaginationArray, SubmissionListResponse> {
    const { account_id, ...query } = params;
    return this._client.getAPIList(
      path`/accounts/${account_id}/email-security/submissions`,
      V4PagePaginationArray<SubmissionListResponse>,
      { query, ...options },
    );
  }
}
export class Submissions extends BaseSubmissions {}

export type SubmissionListResponsesV4PagePaginationArray = V4PagePaginationArray<SubmissionListResponse>;

export interface SubmissionListResponse {
  /**
   * When the submission was requested (UTC).
   */
  requested_at: string;

  submission_id: string;

  customer_status?: 'escalated' | 'reviewed' | 'unreviewed' | null;

  /**
   * The disposition a message is submitted to have.
   */
  escalated_as?: 'MALICIOUS' | 'SUSPICIOUS' | 'SPOOF' | 'SPAM' | 'BULK' | 'NONE' | null;

  /**
   * When the submission was escalated to the security team.
   */
  escalated_at?: string | null;

  /**
   * Email address of the user who escalated the submission.
   */
  escalated_by?: string | null;

  /**
   * Submission ID of the escalated team submission, when this user submission was
   * escalated.
   */
  escalated_submission_id?: string | null;

  /**
   * The disposition a message is submitted to have.
   */
  original_disposition?: 'MALICIOUS' | 'SUSPICIOUS' | 'SPOOF' | 'SPAM' | 'BULK' | 'NONE' | null;

  /**
   * EDF hash of the original message.
   */
  original_edf_hash?: string | null;

  /**
   * The postfix ID of the original message that was submitted.
   */
  original_postfix_id?: string | null;

  /**
   * Processing outcome of the submission.
   */
  outcome?: string | null;

  /**
   * The disposition a message is submitted to have.
   */
  outcome_disposition?: 'MALICIOUS' | 'SUSPICIOUS' | 'SPOOF' | 'SPAM' | 'BULK' | 'NONE' | null;

  /**
   * Email address of the user who requested the submission.
   */
  requested_by?: string | null;

  /**
   * The disposition a message is submitted to have.
   */
  requested_disposition?: 'MALICIOUS' | 'SUSPICIOUS' | 'SPOOF' | 'SPAM' | 'BULK' | 'NONE' | null;

  /**
   * @deprecated Use `requested_at` instead.
   */
  requested_ts?: string;

  /**
   * Processing status of the submission.
   */
  status?: string | null;

  /**
   * Subject line of the submitted message.
   */
  subject?: string | null;

  /**
   * Indicates whether a team member or an end user created the submission.
   */
  type?: 'Team' | 'User' | null;
}

export interface SubmissionListParams extends V4PagePaginationArrayParams {
  /**
   * Path param: Account identifier tag.
   */
  account_id: string;

  /**
   * Query param: The sorting direction.
   */
  direction?: 'asc' | 'desc';

  /**
   * Query param: The end of the search date range. Defaults to `now`.
   */
  end?: string;

  /**
   * Query param: When true, return only submissions that were escalated by an end
   * user (vs. by the security team). When false, return only submissions that were
   * not escalated by an end user. When omitted, no filter is applied.
   */
  escalated_from_user?: boolean;

  /**
   * Query param: Field to sort by.
   */
  order?:
    | 'submission_id'
    | 'subject'
    | 'original_disposition'
    | 'requested_disposition'
    | 'outcome_disposition'
    | 'requested_at';

  /**
   * Query param: The disposition a message is submitted to have.
   */
  original_disposition?: 'MALICIOUS' | 'SUSPICIOUS' | 'SPOOF' | 'SPAM' | 'BULK' | 'NONE';

  /**
   * Query param: The disposition a message is submitted to have.
   */
  outcome_disposition?: 'MALICIOUS' | 'SUSPICIOUS' | 'SPOOF' | 'SPAM' | 'BULK' | 'NONE';

  /**
   * Query param: Search term for filtering submissions.
   */
  query?: string | null;

  /**
   * Query param: The disposition a message is submitted to have.
   */
  requested_disposition?: 'MALICIOUS' | 'SUSPICIOUS' | 'SPOOF' | 'SPAM' | 'BULK' | 'NONE';

  /**
   * Query param: The beginning of the search date range. Defaults to
   * `now - 30 days`.
   */
  start?: string;

  /**
   * Query param: Filter by review status — `escalated`, `reviewed`, or `unreviewed`.
   */
  status?: string;

  /**
   * Query param: Filter by a specific submission ID.
   */
  submission_id?: string;

  /**
   * Query param: Filter by who created the submission — `TEAM` for security team
   * members or `USER` for end users.
   */
  type?: 'TEAM' | 'USER';
}

export declare namespace Submissions {
  export {
    type SubmissionListResponse as SubmissionListResponse,
    type SubmissionListResponsesV4PagePaginationArray as SubmissionListResponsesV4PagePaginationArray,
    type SubmissionListParams as SubmissionListParams,
  };
}