Skip to Content
POST
/api/v1/mailboxes/{mailboxId}/pickups

Configures a remote POP3 email account to automatically fetch messages into this mailbox at a periodic interval.

Authorization

bearerAuth
headerAuthorizationBearer <token>

Two credential kinds share this scheme; GET /api/v1/auth/whoami answers which one you hold and what it reaches.

oek_… API key (minted by POST /api/v1/api-keys; shown once at mint). role: account reaches the full account surface: the directory (domains, routes, patterns, api-keys, accounts, address lists) plus every mailbox the account owns. role: system additionally reaches the operator surface, which is documented separately.

oemp_… mailbox app password (minted by POST /api/v1/identities/{identityId}/credentials). Reaches ONE mailbox: its messages, labels, threads, search, sync, send, filters and PIM collections. Directory routes refuse it with 403 insufficient_scope.

Refusal vocabulary: a missing, malformed, expired, or revoked credential answers 401 unauthorized with a WWW-Authenticate: Bearer challenge; a VALID credential outside its scope answers 403 (insufficient_scope for an app password on a directory route, system_credentials_required where only the operator may call). The public routes (health, branding, token-in-path capabilities) declare security: [].

Path Parameters

mailboxId*string

Mailbox ULID identifier

Request Body

application/json
  1. body
deleteAfterFetch?boolean
host*string
Length1 <= length <= 255
intervalMinutes?integer
Range5 <= value <= 1440
labelName?string
Length1 <= length <= 255
markRead?boolean
mode?string

sync = keep collecting; import = complete once the remote mailbox is drained and quiet for quietDays, then switch off and forget the password

Value in"sync""import"
name?string
Lengthlength <= 128
password*string
Length1 <= length <= 1024
port*integer
Range1 <= value <= 65535
quietDays?integer

Days without a newly stored message, after a drained run, that complete an import (default 7)

Range1 <= value <= 90
tls?string
Value in"tls""starttls"
username*string
Length1 <= length <= 320

Response Body

Created pickup source

application/json
  1. response
completedAt*|

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

Formatint64
consecutiveFailures*integer

Number of consecutive failed polling attempts

Formatint64
createdAt*integer

Creation timestamp in epoch seconds

Formatint64
deleteAfterFetch*boolean

True if messages should be deleted from remote server after fetching

dispatch?|

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

enabled*boolean

True if automatic polling is enabled

host*string

Remote POP3 server hostname (e.g. 'pop.example.com')

id*string

Pickup source ULID

importedTotal?integer

Messages this source has stored (replays excluded), counted as they arrive. ABSENT on the operator listing

Formatint64
intervalMinutes*integer

Polling interval in minutes

Formatint64
labelName*|

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*|

Error message from most recent failed run, or null

lastImportedCount*|

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

Formatint64
lastOversizeCount*|

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

Formatint64
lastRunAt*|

Timestamp of most recent pickup attempt in epoch seconds, or null

Formatint64
lastStatus*|

Outcome status of most recent run, or null

Value in"ok""partial""auth_failed""error"
mailboxId*string

Destination mailbox ULID where fetched mail is deposited

markRead*boolean

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*string

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

Value in"sync""import"
name*|

User-assigned label for this remote account (e.g. 'Old Gmail'), or null

port*integer

Remote POP3 server port (e.g. 995 for TLS, 110 for STARTTLS)

Formatint64
quietDays*integer

Days without a newly stored message, after a drained run, that complete an import (1 to 90). Ignored in sync mode

Formatint64
quietSince?|

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

Formatint64
tls*string

Transport security mode ('tls' or 'starttls')

Value in"tls""starttls"
username*string

Remote POP3 account login username

Example Request
curl -X POST 'https://api.open.email/api/v1/mailboxes/string/pickups' \
  -H 'Content-Type: application/json' \
  -d '{
  "host": "string",
  "password": "string",
  "port": 1,
  "username": "string"
}'
Example Response
{
  "completedAt": 0,
  "consecutiveFailures": 0,
  "createdAt": 0,
  "deleteAfterFetch": true,
  "dispatch": {
    "consecutiveFailures": 0,
    "detail": "string",
    "lastAttemptAt": 0,
    "nextRunAt": 0,
    "outcome": "dispatched"
  },
  "enabled": true,
  "host": "string",
  "id": "string",
  "importedTotal": 0,
  "intervalMinutes": 0,
  "labelName": "string",
  "lastError": "string",
  "lastImportedCount": 0,
  "lastOversizeCount": 0,
  "lastRunAt": 0,
  "lastStatus": "ok",
  "mailboxId": "string",
  "markRead": true,
  "mode": "sync",
  "name": "string",
  "port": 0,
  "quietDays": 0,
  "quietSince": 0,
  "tls": "tls",
  "username": "string"
}