Skip to Content

Update a POP3 pickup source.

Updates configuration settings for a POP3 pickup source such as polling interval, credentials, or enable status.

openemail.pickups.update(
  mailboxId: string,
  pickupId: string,
  body?: PickupsUpdateBody,
  options?: CallOptions,
): ApiPromise<PickupSource>

It calls PATCH /mailboxes/{mailboxId}/pickups/{pickupId}: Update a POP3 pickup source in the API reference.

Example

const pickupSource = await openemail.pickups.update(mailboxId, pickupId, {})

Arguments

ArgumentTypeDescription
mailboxIdstringMailbox ULID identifier. The path's {mailboxId}.
pickupIdstringPickup source identifier. The path's {pickupId}.
bodyPickupsUpdateBodyOptional. The request's body.

Options

It takes no options of its own. Every call also takes signal, timeout, retry and headers, which say how that one call is sent (call options).

Answer

Awaited, it is the API's JSON, PickupSource. It is an ApiPromise: .withResponse() gives the same with the Response it came in, for its headers.

Errors

StatusWhat it means
400validation_failed; source_is_self when the resulting host+username would open the very mailbox this source delivers into; or password_required when re-enabling a completed import without a password
401unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge
404Not found or not accessible
409conflict: destination configuration changed or a handoff is pending; retry
413too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing
503pickup_not_configured — a password change needs PICKUP_KEK, which this deployment has not set. temporary_failure: the mailbox or account is in transition while its store is being adopted; retry after Retry-After

A failed call rejects with a RequestError: its status, and its code, the API's error. Decide on the code: one status covers several.

Types

PickupsUpdateBody

/** The body of `pickups.update`. */
type PickupsUpdateBody = {
  /** Whether to delete messages from remote POP3 server after fetch */
  deleteAfterFetch?: boolean
  /** Whether this pickup source is active. Re-enabling a completed import needs `password` in the same request (400 password_required): completion forgot it */
  enabled?: boolean
  /** POP3 server hostname or IP address */
  host?: string
  /** Polling interval in minutes (5 to 1440) */
  intervalMinutes?: number
  /** Label (folder) fetched mail files into; null clears it back to INBOX */
  labelName?: string | null
  /** Whether every imported message lands read; false = the backlog heuristic (older than the source → read, newer → unread) */
  markRead?: boolean
  /** sync = keep collecting; import = complete once the remote mailbox is drained and quiet for quietDays, then switch off and forget the password */
  mode?: ('sync' | 'import')
  /** Optional display name for this pickup source */
  name?: string | null
  /** POP3 account login password */
  password?: string
  /** POP3 server port number */
  port?: number
  /** Days without a newly stored message, after a drained run, that complete an import (default 7) */
  quietDays?: number
  /** TLS encryption mode ('tls' or 'starttls') */
  tls?: ('tls' | 'starttls')
  /** POP3 account login username */
  username?: string
}

It names these types of the API, each on a page of its own: PickupSource.