cloudflare/src/resources/email-security/investigate/investigate.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 * as DetectionsAPI from './detections';
import { BaseDetections, DetectionGetParams, DetectionGetResponse, Detections } from './detections';
import * as MoveAPI from './move';
import {
  BaseMove,
  Move,
  MoveBulkParams,
  MoveBulkResponse,
  MoveBulkResponsesSinglePage,
  MoveCreateParams,
  MoveCreateResponse,
  MoveCreateResponsesSinglePage,
} from './move';
import * as PreviewAPI from './preview';
import {
  BasePreview,
  Preview,
  PreviewCreateParams,
  PreviewCreateResponse,
  PreviewGetParams,
  PreviewGetResponse,
} from './preview';
import * as RawAPI from './raw';
import { BaseRaw, Raw, RawGetParams, RawGetResponse } from './raw';
import * as ReclassifyAPI from './reclassify';
import { BaseReclassify, Reclassify, ReclassifyCreateParams, ReclassifyCreateResponse } from './reclassify';
import * as ReleaseAPI from './release';
import {
  BaseRelease,
  Release,
  ReleaseBulkParams,
  ReleaseBulkResponse,
  ReleaseBulkResponsesSinglePage,
} from './release';
import * as TraceAPI from './trace';
import { BaseTrace, Trace, TraceGetParams, TraceGetResponse } from './trace';
import * as BulkAPI from './bulk/bulk';
import {
  BaseBulk,
  Bulk,
  BulkCreateParams,
  BulkCreateResponse,
  BulkDeleteParams,
  BulkDeleteResponse,
  BulkGetParams,
  BulkGetResponse,
  BulkListParams,
  BulkListResponse,
  BulkListResponsesV4PagePaginationArray,
} from './bulk/bulk';
import { APIPromise } from '../../../core/api-promise';
import {
  PagePromise,
  V4PagePaginationArray,
  type V4PagePaginationArrayParams,
} from '../../../core/pagination';
import { RequestOptions } from '../../../internal/request-options';
import { path } from '../../../internal/utils/path';

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

  /**
   * Returns information for each email that matches the provided search parameters.
   *
   * @example
   * ```ts
   * // Automatically fetches more pages as needed.
   * for await (const investigateListResponse of client.emailSecurity.investigate.list(
   *   { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
   * )) {
   *   // ...
   * }
   * ```
   */
  list(
    params: InvestigateListParams,
    options?: RequestOptions,
  ): PagePromise<InvestigateListResponsesV4PagePaginationArray, InvestigateListResponse> {
    const { account_id, ...query } = params;
    return this._client.getAPIList(
      path`/accounts/${account_id}/email-security/investigate`,
      V4PagePaginationArray<InvestigateListResponse>,
      { query, ...options },
    );
  }

  /**
   * Retrieves comprehensive details for a specific email message including headers,
   * recipients, sender information, and current quarantine status. Use the
   * investigate_id from search results to fetch detailed information.
   *
   * @example
   * ```ts
   * const investigate =
   *   await client.emailSecurity.investigate.get(
   *     '4Njp3P0STMz2c02Q-2024-01-05T10:00:00-12345678',
   *     { account_id: '023e105f4ecef8ad9ca31a8372d0c353' },
   *   );
   * ```
   */
  get(
    investigateID: string,
    params: InvestigateGetParams,
    options?: RequestOptions,
  ): APIPromise<InvestigateGetResponse> {
    const { account_id, ...query } = params;
    return (
      this._client.get(path`/accounts/${account_id}/email-security/investigate/${investigateID}`, {
        query,
        ...options,
      }) as APIPromise<{ result: InvestigateGetResponse }>
    )._thenUnwrap((obj) => obj.result);
  }
}
export class Investigate extends BaseInvestigate {
  detections: DetectionsAPI.Detections = new DetectionsAPI.Detections(this._client);
  preview: PreviewAPI.Preview = new PreviewAPI.Preview(this._client);
  raw: RawAPI.Raw = new RawAPI.Raw(this._client);
  trace: TraceAPI.Trace = new TraceAPI.Trace(this._client);
  move: MoveAPI.Move = new MoveAPI.Move(this._client);
  reclassify: ReclassifyAPI.Reclassify = new ReclassifyAPI.Reclassify(this._client);
  release: ReleaseAPI.Release = new ReleaseAPI.Release(this._client);
  bulk: BulkAPI.Bulk = new BulkAPI.Bulk(this._client);
}

export type InvestigateListResponsesV4PagePaginationArray = V4PagePaginationArray<InvestigateListResponse>;

export interface InvestigateListResponse {
  /**
   * Unique identifier for a message retrieved from investigation.
   */
  id: string;

  /**
   * @deprecated Use GET /investigate/{investigate_id}/action_log instead.
   */
  action_log: Array<InvestigateListResponse.ActionLog>;

  client_recipients: Array<string>;

  detection_reasons: Array<string>;

  is_phish_submission: boolean;

  is_quarantined: boolean;

  /**
   * The identifier of the message.
   */
  postfix_id: string;

  /**
   * Message processing properties.
   */
  properties: InvestigateListResponse.Properties;

  /**
   * @deprecated Use `scanned_at` instead.
   */
  ts: string;

  alert_id?: string | null;

  delivery_mode?:
    | 'DIRECT'
    | 'BCC'
    | 'JOURNAL'
    | 'REVIEW_SUBMISSION'
    | 'DMARC_UNVERIFIED'
    | 'DMARC_FAILURE_REPORT'
    | 'DMARC_AGGREGATE_REPORT'
    | 'THREAT_INTEL_SUBMISSION'
    | 'SIMULATION_SUBMISSION'
    | 'API'
    | 'RETRO_SCAN'
    | null;

  delivery_status?: Array<
    'delivered' | 'moved' | 'quarantined' | 'rejected' | 'deferred' | 'bounced' | 'queued' | 'move_failed'
  > | null;

  edf_hash?: string | null;

  envelope_from?: string | null;

  envelope_to?: Array<string> | null;

  /**
   * The verdict Email Security assigns to a message.
   */
  final_disposition?:
    | 'MALICIOUS'
    | 'MALICIOUS-BEC'
    | 'SUSPICIOUS'
    | 'SPOOF'
    | 'SPAM'
    | 'BULK'
    | 'ENCRYPTED'
    | 'EXTERNAL'
    | 'UNKNOWN'
    | 'NONE'
    | null;

  /**
   * @deprecated Use the `findings` field from GET
   * /investigate/{investigate_id}/detections instead.
   */
  findings?: Array<InvestigateListResponse.Finding> | null;

  from?: string | null;

  from_name?: string | null;

  htmltext_structure_hash?: string | null;

  message_id?: string | null;

  /**
   * Post-delivery operations performed on this message.
   */
  post_delivery_operations?: Array<'PREVIEW' | 'QUARANTINE_RELEASE' | 'SUBMISSION' | 'MOVE'> | null;

  postfix_id_outbound?: string | null;

  replyto?: string | null;

  /**
   * When the message was scanned (UTC).
   */
  scanned_at?: string | null;

  /**
   * When the message was sent (UTC).
   */
  sent_at?: string | null;

  sent_date?: string | null;

  smtp_helo_server_ip?: string | null;

  smtp_previous_hop_ip?: string | null;

  subject?: string | null;

  threat_categories?: Array<string> | null;

  to?: Array<string> | null;

  to_name?: Array<string> | null;

  validation?: InvestigateListResponse.Validation | null;

  x_originating_ip?: string | null;
}

export namespace InvestigateListResponse {
  export interface ActionLog {
    /**
     * Timestamp when action completed.
     */
    completed_at: string;

    /**
     * Type of action performed.
     */
    operation: 'MOVE' | 'RELEASE' | 'RECLASSIFY' | 'SUBMISSION' | 'QUARANTINE_RELEASE' | 'PREVIEW';

    /**
     * @deprecated Use `completed_at` instead.
     */
    completed_timestamp?: string;

    /**
     * Additional properties for the action.
     */
    properties?: ActionLog.Properties;

    /**
     * Status of the action.
     */
    status?: string | null;
  }

  export namespace ActionLog {
    /**
     * Additional properties for the action.
     */
    export interface Properties {
      /**
       * Target folder for move operations.
       */
      folder?: string;

      /**
       * User who requested the action.
       */
      requested_by?: string;
    }
  }

  /**
   * Message processing properties.
   */
  export interface Properties {
    /**
     * Pattern that allowlisted this message.
     */
    allowlisted_pattern?: string | null;

    /**
     * Type of allowlist pattern.
     */
    allowlisted_pattern_type?:
      | 'quarantine_release'
      | 'acceptable_sender'
      | 'allowed_sender'
      | 'allowed_recipient'
      | 'domain_similarity'
      | 'domain_recency'
      | 'managed_acceptable_sender'
      | 'outbound_ndr'
      | null;

    /**
     * Whether message was blocklisted.
     */
    blocklisted_message?: boolean | null;

    /**
     * Pattern that blocklisted this message.
     */
    blocklisted_pattern?: string | null;

    /**
     * Legacy field for allowlist pattern type.
     */
    whitelisted_pattern_type?:
      | 'quarantine_release'
      | 'acceptable_sender'
      | 'allowed_sender'
      | 'allowed_recipient'
      | 'domain_similarity'
      | 'domain_recency'
      | 'managed_acceptable_sender'
      | 'outbound_ndr'
      | null;
  }

  export interface Finding {
    attachment?: string | null;

    detail?: string | null;

    /**
     * The verdict Email Security assigns to a message.
     */
    detection?:
      | 'MALICIOUS'
      | 'MALICIOUS-BEC'
      | 'SUSPICIOUS'
      | 'SPOOF'
      | 'SPAM'
      | 'BULK'
      | 'ENCRYPTED'
      | 'EXTERNAL'
      | 'UNKNOWN'
      | 'NONE'
      | null;

    field?: string | null;

    name?: string | null;

    portion?: string | null;

    reason?: string | null;

    score?: number | null;

    value?: string | null;
  }

  export interface Validation {
    comment?: string | null;

    dkim?: 'pass' | 'neutral' | 'fail' | 'error' | 'none' | null;

    dmarc?: 'pass' | 'neutral' | 'fail' | 'error' | 'none' | null;

    spf?: 'pass' | 'neutral' | 'fail' | 'error' | 'none' | null;
  }
}

export interface InvestigateGetResponse {
  /**
   * Unique identifier for a message retrieved from investigation.
   */
  id: string;

  /**
   * @deprecated Use GET /investigate/{investigate_id}/action_log instead.
   */
  action_log: Array<InvestigateGetResponse.ActionLog>;

  client_recipients: Array<string>;

  detection_reasons: Array<string>;

  is_phish_submission: boolean;

  is_quarantined: boolean;

  /**
   * The identifier of the message.
   */
  postfix_id: string;

  /**
   * Message processing properties.
   */
  properties: InvestigateGetResponse.Properties;

  /**
   * @deprecated Use `scanned_at` instead.
   */
  ts: string;

  alert_id?: string | null;

  delivery_mode?:
    | 'DIRECT'
    | 'BCC'
    | 'JOURNAL'
    | 'REVIEW_SUBMISSION'
    | 'DMARC_UNVERIFIED'
    | 'DMARC_FAILURE_REPORT'
    | 'DMARC_AGGREGATE_REPORT'
    | 'THREAT_INTEL_SUBMISSION'
    | 'SIMULATION_SUBMISSION'
    | 'API'
    | 'RETRO_SCAN'
    | null;

  delivery_status?: Array<
    'delivered' | 'moved' | 'quarantined' | 'rejected' | 'deferred' | 'bounced' | 'queued' | 'move_failed'
  > | null;

  edf_hash?: string | null;

  envelope_from?: string | null;

  envelope_to?: Array<string> | null;

  /**
   * The verdict Email Security assigns to a message.
   */
  final_disposition?:
    | 'MALICIOUS'
    | 'MALICIOUS-BEC'
    | 'SUSPICIOUS'
    | 'SPOOF'
    | 'SPAM'
    | 'BULK'
    | 'ENCRYPTED'
    | 'EXTERNAL'
    | 'UNKNOWN'
    | 'NONE'
    | null;

  /**
   * @deprecated Use the `findings` field from GET
   * /investigate/{investigate_id}/detections instead.
   */
  findings?: Array<InvestigateGetResponse.Finding> | null;

  from?: string | null;

  from_name?: string | null;

  htmltext_structure_hash?: string | null;

  message_id?: string | null;

  /**
   * Post-delivery operations performed on this message.
   */
  post_delivery_operations?: Array<'PREVIEW' | 'QUARANTINE_RELEASE' | 'SUBMISSION' | 'MOVE'> | null;

  postfix_id_outbound?: string | null;

  replyto?: string | null;

  /**
   * When the message was scanned (UTC).
   */
  scanned_at?: string | null;

  /**
   * When the message was sent (UTC).
   */
  sent_at?: string | null;

  sent_date?: string | null;

  smtp_helo_server_ip?: string | null;

  smtp_previous_hop_ip?: string | null;

  subject?: string | null;

  threat_categories?: Array<string> | null;

  to?: Array<string> | null;

  to_name?: Array<string> | null;

  validation?: InvestigateGetResponse.Validation | null;

  x_originating_ip?: string | null;
}

export namespace InvestigateGetResponse {
  export interface ActionLog {
    /**
     * Timestamp when action completed.
     */
    completed_at: string;

    /**
     * Type of action performed.
     */
    operation: 'MOVE' | 'RELEASE' | 'RECLASSIFY' | 'SUBMISSION' | 'QUARANTINE_RELEASE' | 'PREVIEW';

    /**
     * @deprecated Use `completed_at` instead.
     */
    completed_timestamp?: string;

    /**
     * Additional properties for the action.
     */
    properties?: ActionLog.Properties;

    /**
     * Status of the action.
     */
    status?: string | null;
  }

  export namespace ActionLog {
    /**
     * Additional properties for the action.
     */
    export interface Properties {
      /**
       * Target folder for move operations.
       */
      folder?: string;

      /**
       * User who requested the action.
       */
      requested_by?: string;
    }
  }

  /**
   * Message processing properties.
   */
  export interface Properties {
    /**
     * Pattern that allowlisted this message.
     */
    allowlisted_pattern?: string | null;

    /**
     * Type of allowlist pattern.
     */
    allowlisted_pattern_type?:
      | 'quarantine_release'
      | 'acceptable_sender'
      | 'allowed_sender'
      | 'allowed_recipient'
      | 'domain_similarity'
      | 'domain_recency'
      | 'managed_acceptable_sender'
      | 'outbound_ndr'
      | null;

    /**
     * Whether message was blocklisted.
     */
    blocklisted_message?: boolean | null;

    /**
     * Pattern that blocklisted this message.
     */
    blocklisted_pattern?: string | null;

    /**
     * Legacy field for allowlist pattern type.
     */
    whitelisted_pattern_type?:
      | 'quarantine_release'
      | 'acceptable_sender'
      | 'allowed_sender'
      | 'allowed_recipient'
      | 'domain_similarity'
      | 'domain_recency'
      | 'managed_acceptable_sender'
      | 'outbound_ndr'
      | null;
  }

  export interface Finding {
    attachment?: string | null;

    detail?: string | null;

    /**
     * The verdict Email Security assigns to a message.
     */
    detection?:
      | 'MALICIOUS'
      | 'MALICIOUS-BEC'
      | 'SUSPICIOUS'
      | 'SPOOF'
      | 'SPAM'
      | 'BULK'
      | 'ENCRYPTED'
      | 'EXTERNAL'
      | 'UNKNOWN'
      | 'NONE'
      | null;

    field?: string | null;

    name?: string | null;

    portion?: string | null;

    reason?: string | null;

    score?: number | null;

    value?: string | null;
  }

  export interface Validation {
    comment?: string | null;

    dkim?: 'pass' | 'neutral' | 'fail' | 'error' | 'none' | null;

    dmarc?: 'pass' | 'neutral' | 'fail' | 'error' | 'none' | null;

    spf?: 'pass' | 'neutral' | 'fail' | 'error' | 'none' | null;
  }
}

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

  /**
   * Query param: Filter by alert ID.
   */
  alert_id?: string;

  /**
   * Query param: Pagination cursor from the previous response's `result_info`.
   */
  cursor?: string;

  /**
   * Query param: Delivery status to filter by.
   */
  delivery_status?:
    | 'delivered'
    | 'moved'
    | 'quarantined'
    | 'rejected'
    | 'deferred'
    | 'bounced'
    | 'queued'
    | 'move_failed';

  /**
   * Query param: Whether to include only detections in search results.
   */
  detections_only?: boolean;

  /**
   * Query param: Filter by a domain found in the email — sender domain, recipient
   * domain, or a domain in a link.
   */
  domain?: string;

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

  /**
   * Query param: Dispositions to filter by.
   */
  final_disposition?: 'MALICIOUS' | 'SUSPICIOUS' | 'SPOOF' | 'SPAM' | 'BULK' | 'NONE';

  /**
   * Query param: Message actions to filter by.
   */
  message_action?: 'PREVIEW' | 'QUARANTINE_RELEASED' | 'MOVED';

  /**
   * Query param: Filter by the RFC 5322 Message-ID header.
   */
  message_id?: string;

  /**
   * Query param: Metric to aggregate the results by.
   */
  metric?: string;

  /**
   * Query param: Space-delimited term matched case-insensitively against message
   * metadata — sender, recipient, subject, attachment names and hashes, and message
   * ID.
   */
  query?: string;

  /**
   * Query param: Filter by recipient. Matches an email address or a domain.
   */
  recipient?: string;

  /**
   * Query param: Filter by sender. Matches an email address or a domain.
   */
  sender?: string;

  /**
   * Query param: Matches messages whose SMTP HELO server IP address equals this
   * value.
   */
  smtp_helo_ip?: string;

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

  /**
   * Query param: Search for messages containing individual keywords in any order
   * within the subject.
   */
  subject?: string;
}

export interface InvestigateGetParams {
  /**
   * Path param: Account identifier tag.
   */
  account_id: string;

  /**
   * Query param: When true, search the submissions datastore only. When false or
   * omitted, search the regular datastore only.
   */
  submission?: boolean;
}

Investigate.Detections = Detections;
Investigate.BaseDetections = BaseDetections;
Investigate.Preview = Preview;
Investigate.BasePreview = BasePreview;
Investigate.Raw = Raw;
Investigate.BaseRaw = BaseRaw;
Investigate.Trace = Trace;
Investigate.BaseTrace = BaseTrace;
Investigate.Move = Move;
Investigate.BaseMove = BaseMove;
Investigate.Reclassify = Reclassify;
Investigate.BaseReclassify = BaseReclassify;
Investigate.Release = Release;
Investigate.BaseRelease = BaseRelease;
Investigate.Bulk = Bulk;
Investigate.BaseBulk = BaseBulk;

export declare namespace Investigate {
  export {
    type InvestigateListResponse as InvestigateListResponse,
    type InvestigateGetResponse as InvestigateGetResponse,
    type InvestigateListResponsesV4PagePaginationArray as InvestigateListResponsesV4PagePaginationArray,
    type InvestigateListParams as InvestigateListParams,
    type InvestigateGetParams as InvestigateGetParams,
  };

  export {
    Detections as Detections,
    BaseDetections as BaseDetections,
    type DetectionGetResponse as DetectionGetResponse,
    type DetectionGetParams as DetectionGetParams,
  };

  export {
    Preview as Preview,
    BasePreview as BasePreview,
    type PreviewCreateResponse as PreviewCreateResponse,
    type PreviewGetResponse as PreviewGetResponse,
    type PreviewCreateParams as PreviewCreateParams,
    type PreviewGetParams as PreviewGetParams,
  };

  export {
    Raw as Raw,
    BaseRaw as BaseRaw,
    type RawGetResponse as RawGetResponse,
    type RawGetParams as RawGetParams,
  };

  export {
    Trace as Trace,
    BaseTrace as BaseTrace,
    type TraceGetResponse as TraceGetResponse,
    type TraceGetParams as TraceGetParams,
  };

  export {
    Move as Move,
    BaseMove as BaseMove,
    type MoveCreateResponse as MoveCreateResponse,
    type MoveBulkResponse as MoveBulkResponse,
    type MoveCreateResponsesSinglePage as MoveCreateResponsesSinglePage,
    type MoveBulkResponsesSinglePage as MoveBulkResponsesSinglePage,
    type MoveCreateParams as MoveCreateParams,
    type MoveBulkParams as MoveBulkParams,
  };

  export {
    Reclassify as Reclassify,
    BaseReclassify as BaseReclassify,
    type ReclassifyCreateResponse as ReclassifyCreateResponse,
    type ReclassifyCreateParams as ReclassifyCreateParams,
  };

  export {
    Release as Release,
    BaseRelease as BaseRelease,
    type ReleaseBulkResponse as ReleaseBulkResponse,
    type ReleaseBulkResponsesSinglePage as ReleaseBulkResponsesSinglePage,
    type ReleaseBulkParams as ReleaseBulkParams,
  };

  export {
    Bulk as Bulk,
    BaseBulk as BaseBulk,
    type BulkCreateResponse as BulkCreateResponse,
    type BulkListResponse as BulkListResponse,
    type BulkDeleteResponse as BulkDeleteResponse,
    type BulkGetResponse as BulkGetResponse,
    type BulkListResponsesV4PagePaginationArray as BulkListResponsesV4PagePaginationArray,
    type BulkCreateParams as BulkCreateParams,
    type BulkListParams as BulkListParams,
    type BulkDeleteParams as BulkDeleteParams,
    type BulkGetParams as BulkGetParams,
  };
}