# Update a POP3 pickup source

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

## `PATCH /api/v1/mailboxes/{mailboxId}/pickups/{pickupId}`

### Path parameters

- `mailboxId` (string, required) — Mailbox ULID identifier
- `pickupId` (string, required) — Pickup source identifier

### Request body (optional)

`application/json`

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

### Responses

**200** — Updated pickup source details

`application/json` → PickupSource

- `completedAt` (integer | null, required) — When an import completed, epoch seconds; null while it runs, and always in sync mode. A completed source is disabled and holds no password: re-enabling it needs the password again
- `consecutiveFailures` (integer <int64>, required) — Number of consecutive failed polling attempts
- `createdAt` (integer <int64>, required) — Creation timestamp in epoch seconds
- `deleteAfterFetch` (boolean, required) — True if messages should be deleted from remote server after fetching
- `enabled` (boolean, required) — True if automatic polling is enabled
- `host` (string, required) — Remote POP3 server hostname (e.g. 'pop.example.com')
- `id` (string, required) — Pickup source ULID
- `intervalMinutes` (integer <int64>, required) — Polling interval in minutes
- `labelName` (string | null, required) — Label (folder) fetched mail files into; null = INBOX. Created on first use if missing. An explicit destination is not spam-scored; a Sieve fileinto still wins; a blocked sender still files to Junk
- `lastError` (string | null, required) — Error message from most recent failed run, or null
- `lastImportedCount` (integer | null, required) — Messages the fetcher uploaded on the most recent completed run (its report's uploadedCount). Null until a run has reported; 0 is a run that found nothing waiting
- `lastOversizeCount` (integer | null, required) — Messages the fetcher left on the remote server on its most recent run because they are over the platform's message size limit; they are never imported and do not hold an import open. Null until a run has reported it
- `lastRunAt` (integer | null, required) — Timestamp of most recent pickup attempt in epoch seconds, or null
- `lastStatus` ("ok" | "partial" | "auth_failed" | "error", required) — Outcome status of most recent run, or null
- `mailboxId` (string, required) — Destination mailbox ULID where fetched mail is deposited
- `markRead` (boolean, required) — True if every imported message lands read. False (the default): messages dated before the source was added — the backlog — land read, newer ones unread; POP3 itself carries no read state
- `mode` ("sync" | "import", required) — sync = keep collecting from this account for as long as the source exists. import = move off this account: the source completes itself once a run finds the remote mailbox drained and no new message has been stored for quietDays, then switches off and forgets the remote password
- `name` (string | null, required) — User-assigned label for this remote account (e.g. 'Old Gmail'), or null
- `port` (integer <int64>, required) — Remote POP3 server port (e.g. 995 for TLS, 110 for STARTTLS)
- `quietDays` (integer <int64>, required) — Days without a newly stored message, after a drained run, that complete an import (1 to 90). Ignored in sync mode
- `tls` ("tls" | "starttls", required) — Transport security mode ('tls' or 'starttls')
- `username` (string, required) — Remote POP3 account login username
- `dispatch` (PickupDispatch) — State of the last attempt to hand this source to the fetcher, read from the scheduler. Null when that read was not made (it failed, or the page exceeded the fan-out bound) — never to mean 'nothing happened', which is an object with a null outcome. ABSENT on the operator listing, which is a deliberately DO-free cross-tenant scan
  - `consecutiveFailures` (integer <int64>, required) — Dispatch attempts failed in a row; 0 once one is accepted
  - `detail` (string | null, required) — The refusal status, the transport error, the name of the blank var, or the receive hold's code — whichever the outcome implies
  - `lastAttemptAt` (integer | null, required) — When the fetcher was last called, epoch ms, or null if never
  - `nextRunAt` (integer | null, required) — When the next attempt is armed for, epoch ms
  - `outcome` ("dispatched" | "busy" | "rejected" | "unreachable" | "decrypt_failed" | "unconfigured" | "receive_hold", required) — dispatched = accepted; busy = a run was already in progress (also fine); rejected = the fetcher answered and said no; unreachable = no answer at all; decrypt_failed = the stored password would not decrypt (PICKUP_KEK); unconfigured = a required var is blank; receive_hold = the destination mailbox's receive hold is set (detail: receiving_paused or receiving_disabled), so nothing was collected, the source keeps its schedule and resumes once the hold is cleared. Null when nothing has been dispatched yet
- `importedTotal` (integer <int64>) — Messages this source has stored (replays excluded), counted as they arrive. ABSENT on the operator listing
- `quietSince` (integer | null) — When the quiet window last restarted (a message was stored, the source was re-enabled or switched to import), epoch seconds; null = since createdAt. ABSENT on the operator listing

**400** — validation_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

`application/json` → ErrorOrValidation

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**404** — Not found or not accessible

`application/json` → ErrorBody

**409** — conflict: destination configuration changed or a handoff is pending; retry

`application/json` → ErrorBody

**413** — too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing

`application/json` → ErrorBody

**503** — pickup_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

`application/json` → ErrorBody

### Example request

```bash
curl -X PATCH 'https://api.open.email/api/v1/mailboxes/{mailboxId}/pickups/{pickupId}' \
  -H 'Authorization: Bearer oek_…' \
  -H 'Content-Type: application/json' \
  -d '{}'
```

## TypeScript SDK

[`openemail.pickups.update`](/docs/sdks/typescript/pickups/update)

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