shardpostctl-learning(1) – ShardPost docs

SHARDPOSTCTL-LEARNING(1)

ShardPost Manual

SHARDPOSTCTL-LEARNING(1)

NAME

shardpostctl-learning - inspect and retry jobs of the learning queue

SYNOPSIS

shardpostctl learning list [-account account] [-state state] [-limit n] [-after id] [--json]
shardpostctl learning show [--json] job-id
shardpostctl learning retry [-confirm-repeat] [--json] job-id

DESCRIPTION

When a user moves a message into the junk mailbox (or out of it), IMAPSieve queues a learning job. A worker hands the message to the configured program, for example a spam filter's learn command, retries with backoff and gives up after imapsieve.learning.max_attempts attempts. These commands look at that queue and put a dead job back into it.

learning list

The queue, oldest job id first, with account, program, state, attempts and the next attempt. -state narrows it to pending, dead or delivered. A client with an account scope must pass -account. With imapsieve.learning.index: read the server reads the queue's owner index instead of listing the queue. Role: diagnose.

learning show

One job in detail: account, mailbox id, program, state, attempts, manual retries, size, creation time and next attempt. The message itself is never printed. Role: diagnose.

learning retry

Makes a dead job due again: the attempt counter starts over and the worker picks it up on its next pass (with imapsieve.learning.index: read at once, woken by the queue).

Learning programs are not idempotent. A message learned twice counts twice and skews the filter, and a job can be dead although its program already received the message (a timeout after the handover, for example). Therefore a job that was attempted before is only retried with -confirm-repeat. A job whose message was never committed to the store (no receipt) cannot be retried at all: there is nothing left to learn.

Only dead jobs can be retried. A pending job is already scheduled, and a delivered one is on its way out of the queue.

Role: repair.

OPTIONS

-account account: Only jobs of this account.
-state pending|dead|delivered: Only jobs in this state.
-limit n: Jobs per page (up to 500).
-after id: Continue after this job id.
-confirm-repeat: Retry although the program may already have seen this message.
--json: Print the answer as JSON.

EXAMPLES

Is the queue backing up, and is anything dead?

shardpostctl learning list -limit 20
shardpostctl learning list -state dead

A user says "marking as spam has no effect": look at their jobs.

shardpostctl learning list -account user@example.org
shardpostctl learning show 6f1c...e2

The spam filter was down for an hour. Put the jobs that died because of it back into the queue, accepting that a message may be learned twice:

for id in $(shardpostctl learning list -state dead --json \


        | jq -r '.items[].id'); do


    shardpostctl learning retry -confirm-repeat "$id"
done

A job that never reached its program (no attempt yet) needs no confirmation:

shardpostctl learning retry 6f1c...e2

EXIT STATUS

0: Done.
65: The job is not dead, its message was never committed, or it was attempted and -confirm-repeat was not given.
67: No such learning job.
75: The learning queue is not available on this server.
77: The caller lacks the role, or the job belongs to an account outside its scope.