List bulk action jobs

client.EmailSecurity.Investigate.Bulk.List(ctx, params) (*V4PagePaginationArray[InvestigateBulkListResponse], error)

GET/accounts/{account_id}/email-security/investigate/bulk

Returns a paginated list of bulk action jobs for the account.

Security

API Token

The preferred authorization scheme for interacting with the Cloudflare API. Create a token.

Example:Authorization: Bearer Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY

API Email + API Key

The previous authorization scheme for interacting with the Cloudflare API, used in conjunction with a Global API key.

Example:X-Auth-Email: user@example.com

The previous authorization scheme for interacting with the Cloudflare API. When possible, use API tokens instead of Global API keys.

Example:X-Auth-Key: 144c9defac04969c7bfad8efaa8ea194

Accepted Permissions (at least one required)

Cloud Email Security: WriteCloud Email Security: Read

ParametersExpand Collapse

params InvestigateBulkListParams

AccountID param.Field[string]

Path param: Identifier.

maxLength32

ActionType param.Field[InvestigateBulkListParamsActionType]Optional

Query param: Filter jobs by the action they perform.

const InvestigateBulkListParamsActionTypeMove InvestigateBulkListParamsActionType = "MOVE"

const InvestigateBulkListParamsActionTypeRelease InvestigateBulkListParamsActionType = "RELEASE"

Page param.Field[int64]Optional

Query param: Current page within paginated list of results.

minimum1

PerPage param.Field[int64]Optional

Query param: The number of results per page. Maximum value is 1000.

maximum1000

minimum1

Status param.Field[InvestigateBulkListParamsStatus]Optional

Query param: Filter jobs by their processing status.

const InvestigateBulkListParamsStatusPending InvestigateBulkListParamsStatus = "PENDING"

const InvestigateBulkListParamsStatusDiscovering InvestigateBulkListParamsStatus = "DISCOVERING"

const InvestigateBulkListParamsStatusProcessing InvestigateBulkListParamsStatus = "PROCESSING"

const InvestigateBulkListParamsStatusCompleted InvestigateBulkListParamsStatus = "COMPLETED"

const InvestigateBulkListParamsStatusFailed InvestigateBulkListParamsStatus = "FAILED"

const InvestigateBulkListParamsStatusCancelled InvestigateBulkListParamsStatus = "CANCELLED"

ReturnsExpand Collapse

type InvestigateBulkListResponse struct{…}

ActionParams InvestigateBulkListResponseActionParams

One of the following:

type InvestigateBulkListResponseActionParamsMove struct{…}

Destination InvestigateBulkListResponseActionParamsMoveDestination

The mailbox folder to move messages to.

One of the following:

const InvestigateBulkListResponseActionParamsMoveDestinationInbox InvestigateBulkListResponseActionParamsMoveDestination = "Inbox"

const InvestigateBulkListResponseActionParamsMoveDestinationJunkEmail InvestigateBulkListResponseActionParamsMoveDestination = "JunkEmail"

const InvestigateBulkListResponseActionParamsMoveDestinationDeletedItems InvestigateBulkListResponseActionParamsMoveDestination = "DeletedItems"

const InvestigateBulkListResponseActionParamsMoveDestinationRecoverableItemsDeletions InvestigateBulkListResponseActionParamsMoveDestination = "RecoverableItemsDeletions"

const InvestigateBulkListResponseActionParamsMoveDestinationRecoverableItemsPurges InvestigateBulkListResponseActionParamsMoveDestination = "RecoverableItemsPurges"

Type InvestigateBulkListResponseActionParamsMoveType

DeprecatedExpectedDisposition InvestigateBulkListResponseActionParamsMoveExpectedDispositionOptional

This field is nonfunctional.

Nonfunctional field. End of life: December 1, 2026.

One of the following:

const InvestigateBulkListResponseActionParamsMoveExpectedDispositionMalicious InvestigateBulkListResponseActionParamsMoveExpectedDisposition = "MALICIOUS"

const InvestigateBulkListResponseActionParamsMoveExpectedDispositionMaliciousBec InvestigateBulkListResponseActionParamsMoveExpectedDisposition = "MALICIOUS-BEC"

const InvestigateBulkListResponseActionParamsMoveExpectedDispositionSuspicious InvestigateBulkListResponseActionParamsMoveExpectedDisposition = "SUSPICIOUS"

const InvestigateBulkListResponseActionParamsMoveExpectedDispositionSpoof InvestigateBulkListResponseActionParamsMoveExpectedDisposition = "SPOOF"

const InvestigateBulkListResponseActionParamsMoveExpectedDispositionSpam InvestigateBulkListResponseActionParamsMoveExpectedDisposition = "SPAM"

const InvestigateBulkListResponseActionParamsMoveExpectedDispositionBulk InvestigateBulkListResponseActionParamsMoveExpectedDisposition = "BULK"

const InvestigateBulkListResponseActionParamsMoveExpectedDispositionEncrypted InvestigateBulkListResponseActionParamsMoveExpectedDisposition = "ENCRYPTED"

const InvestigateBulkListResponseActionParamsMoveExpectedDispositionExternal InvestigateBulkListResponseActionParamsMoveExpectedDisposition = "EXTERNAL"

const InvestigateBulkListResponseActionParamsMoveExpectedDispositionUnknown InvestigateBulkListResponseActionParamsMoveExpectedDisposition = "UNKNOWN"

const InvestigateBulkListResponseActionParamsMoveExpectedDispositionNone InvestigateBulkListResponseActionParamsMoveExpectedDisposition = "NONE"

type InvestigateBulkListResponseActionParamsRelease struct{…}

Type InvestigateBulkListResponseActionParamsReleaseType

ActionType InvestigateBulkListResponseActionType

One of the following:

const InvestigateBulkListResponseActionTypeMove InvestigateBulkListResponseActionType = "MOVE"

const InvestigateBulkListResponseActionTypeRelease InvestigateBulkListResponseActionType = "RELEASE"

CreatedAt Time

formatdate-time

JobID string

formatuuid

MessagesCancelled int64

Messages that were cancelled: rows cancelled via the API before being claimed, and rows whose in-flight attempt ended when the job reached a terminal state. Together the counters satisfy total_messages_discovered = messages_pending + messages_successful + messages_failed + messages_skipped + messages_cancelled.

MessagesFailed int64

MessagesPending int64

MessagesSkipped int64

Messages that discovery skipped (for example, phish submissions, which the job cannot action).

MessagesSuccessful int64

SearchParams InvestigateBulkListResponseSearchParams

DeprecatedActionLog boolOptional

Use GET /investigate/{investigate_id}/action_log instead.

Deprecated, use GET /investigate/{investigate_id}/action_log instead. End of life: November 1, 2026.

AlertID stringOptional

Alert ID of the detection to filter by.

DeliveryStatus InvestigateBulkListResponseSearchParamsDeliveryStatusOptional

Delivery status to filter by.

One of the following:

const InvestigateBulkListResponseSearchParamsDeliveryStatusDelivered InvestigateBulkListResponseSearchParamsDeliveryStatus = "delivered"

const InvestigateBulkListResponseSearchParamsDeliveryStatusMoved InvestigateBulkListResponseSearchParamsDeliveryStatus = "moved"

const InvestigateBulkListResponseSearchParamsDeliveryStatusQuarantined InvestigateBulkListResponseSearchParamsDeliveryStatus = "quarantined"

const InvestigateBulkListResponseSearchParamsDeliveryStatusRejected InvestigateBulkListResponseSearchParamsDeliveryStatus = "rejected"

const InvestigateBulkListResponseSearchParamsDeliveryStatusDeferred InvestigateBulkListResponseSearchParamsDeliveryStatus = "deferred"

const InvestigateBulkListResponseSearchParamsDeliveryStatusBounced InvestigateBulkListResponseSearchParamsDeliveryStatus = "bounced"

const InvestigateBulkListResponseSearchParamsDeliveryStatusQueued InvestigateBulkListResponseSearchParamsDeliveryStatus = "queued"

const InvestigateBulkListResponseSearchParamsDeliveryStatusMoveFailed InvestigateBulkListResponseSearchParamsDeliveryStatus = "move_failed"

DetectionsOnly boolOptional

Whether to include only detections in search results.

Domain stringOptional

Match messages that mention this domain — sender domain, recipient domain, or a domain in a link.

End TimeOptional

End of search date range.

formatdate-time

ExactSubject stringOptional

Match messages whose subject line equals this value exactly.

FinalDisposition InvestigateBulkListResponseSearchParamsFinalDispositionOptional

Dispositions to filter by.

One of the following:

const InvestigateBulkListResponseSearchParamsFinalDispositionMalicious InvestigateBulkListResponseSearchParamsFinalDisposition = "MALICIOUS"

const InvestigateBulkListResponseSearchParamsFinalDispositionMaliciousBec InvestigateBulkListResponseSearchParamsFinalDisposition = "MALICIOUS-BEC"

const InvestigateBulkListResponseSearchParamsFinalDispositionSuspicious InvestigateBulkListResponseSearchParamsFinalDisposition = "SUSPICIOUS"

const InvestigateBulkListResponseSearchParamsFinalDispositionSpoof InvestigateBulkListResponseSearchParamsFinalDisposition = "SPOOF"

const InvestigateBulkListResponseSearchParamsFinalDispositionSpam InvestigateBulkListResponseSearchParamsFinalDisposition = "SPAM"

const InvestigateBulkListResponseSearchParamsFinalDispositionBulk InvestigateBulkListResponseSearchParamsFinalDisposition = "BULK"

const InvestigateBulkListResponseSearchParamsFinalDispositionEncrypted InvestigateBulkListResponseSearchParamsFinalDisposition = "ENCRYPTED"

const InvestigateBulkListResponseSearchParamsFinalDispositionExternal InvestigateBulkListResponseSearchParamsFinalDisposition = "EXTERNAL"

const InvestigateBulkListResponseSearchParamsFinalDispositionUnknown InvestigateBulkListResponseSearchParamsFinalDisposition = "UNKNOWN"

const InvestigateBulkListResponseSearchParamsFinalDispositionNone InvestigateBulkListResponseSearchParamsFinalDisposition = "NONE"

MessageAction InvestigateBulkListResponseSearchParamsMessageActionOptional

Message actions to filter by.

One of the following:

const InvestigateBulkListResponseSearchParamsMessageActionPreview InvestigateBulkListResponseSearchParamsMessageAction = "PREVIEW"

const InvestigateBulkListResponseSearchParamsMessageActionQuarantineReleased InvestigateBulkListResponseSearchParamsMessageAction = "QUARANTINE_RELEASED"

const InvestigateBulkListResponseSearchParamsMessageActionMoved InvestigateBulkListResponseSearchParamsMessageAction = "MOVED"

MessageID stringOptional

Message-ID header value to filter by.

Metric stringOptional

Metric name to filter the search by.

Query stringOptional

Space-delimited search term. Case-insensitive.

Recipient stringOptional

Match messages whose recipient is this email address or domain.

Sender stringOptional

Match messages whose sender is this email address or domain.

SmtpHeloIP stringOptional

Matches messages whose SMTP HELO server IP address equals this value.

Start TimeOptional

Beginning of search date range.

formatdate-time

Subject stringOptional

Match messages whose subject contains these keywords, in any order.

Submissions boolOptional

Whether to search reclassification submissions instead of original messages.

Status InvestigateBulkListResponseStatus

Status of a bulk action job.

One of the following:

const InvestigateBulkListResponseStatusPending InvestigateBulkListResponseStatus = "PENDING"

const InvestigateBulkListResponseStatusDiscovering InvestigateBulkListResponseStatus = "DISCOVERING"

const InvestigateBulkListResponseStatusProcessing InvestigateBulkListResponseStatus = "PROCESSING"

const InvestigateBulkListResponseStatusCompleted InvestigateBulkListResponseStatus = "COMPLETED"

const InvestigateBulkListResponseStatusFailed InvestigateBulkListResponseStatus = "FAILED"

const InvestigateBulkListResponseStatusCancelled InvestigateBulkListResponseStatus = "CANCELLED"

TotalMessagesDiscovered int64

Comment stringOptional

CompletedAt TimeOptional

formatdate-time

StartedAt TimeOptional

formatdate-time

StatusMessage stringOptional

List bulk action jobs

package main

import (
  "context"
  "fmt"

  "github.com/cloudflare/cloudflare-go"
  "github.com/cloudflare/cloudflare-go/email_security"
  "github.com/cloudflare/cloudflare-go/option"
)

func main() {
  client := cloudflare.NewClient(
    option.WithAPIToken("Sn3lZJTBX6kkg7OdcBUAxOO963GEIyGQqnFTOFYY"),
  )
  page, err := client.EmailSecurity.Investigate.Bulk.List(context.TODO(), email_security.InvestigateBulkListParams{
    AccountID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", page)
}

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": [
    {
      "action_params": {
        "destination": "Inbox",
        "type": "MOVE",
        "expected_disposition": "MALICIOUS"
      },
      "action_type": "MOVE",
      "created_at": "2019-12-27T18:11:19.117Z",
      "job_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "messages_cancelled": 0,
      "messages_failed": 0,
      "messages_pending": 0,
      "messages_skipped": 0,
      "messages_successful": 0,
      "search_params": {
        "action_log": true,
        "alert_id": "alert_id",
        "delivery_status": "delivered",
        "detections_only": true,
        "domain": "domain",
        "end": "2022-07-25T14:30:00Z",
        "exact_subject": "exact_subject",
        "final_disposition": "MALICIOUS",
        "message_action": "PREVIEW",
        "message_id": "message_id",
        "metric": "metric",
        "query": "query",
        "recipient": "recipient",
        "sender": "sender",
        "smtp_helo_ip": "smtp_helo_ip",
        "start": "2022-06-25T14:30:00Z",
        "subject": "subject",
        "submissions": true
      },
      "status": "PENDING",
      "total_messages_discovered": 0,
      "comment": "comment",
      "completed_at": "2019-12-27T18:11:19.117Z",
      "started_at": "2019-12-27T18:11:19.117Z",
      "status_message": "status_message"
    }
  ],
  "result_info": {
    "count": 0,
    "per_page": 0,
    "total_count": 0,
    "next": "next",
    "page": 0,
    "previous": "previous"
  },
  "success": true
}

Returns Examples

{
  "errors": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "messages": [
    {
      "code": 1000,
      "message": "message",
      "documentation_url": "documentation_url",
      "source": {
        "pointer": "pointer"
      }
    }
  ],
  "result": [
    {
      "action_params": {
        "destination": "Inbox",
        "type": "MOVE",
        "expected_disposition": "MALICIOUS"
      },
      "action_type": "MOVE",
      "created_at": "2019-12-27T18:11:19.117Z",
      "job_id": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
      "messages_cancelled": 0,
      "messages_failed": 0,
      "messages_pending": 0,
      "messages_skipped": 0,
      "messages_successful": 0,
      "search_params": {
        "action_log": true,
        "alert_id": "alert_id",
        "delivery_status": "delivered",
        "detections_only": true,
        "domain": "domain",
        "end": "2022-07-25T14:30:00Z",
        "exact_subject": "exact_subject",
        "final_disposition": "MALICIOUS",
        "message_action": "PREVIEW",
        "message_id": "message_id",
        "metric": "metric",
        "query": "query",
        "recipient": "recipient",
        "sender": "sender",
        "smtp_helo_ip": "smtp_helo_ip",
        "start": "2022-06-25T14:30:00Z",
        "subject": "subject",
        "submissions": true
      },
      "status": "PENDING",
      "total_messages_discovered": 0,
      "comment": "comment",
      "completed_at": "2019-12-27T18:11:19.117Z",
      "started_at": "2019-12-27T18:11:19.117Z",
      "status_message": "status_message"
    }
  ],
  "result_info": {
    "count": 0,
    "per_page": 0,
    "total_count": 0,
    "next": "next",
    "page": 0,
    "previous": "previous"
  },
  "success": true
}