# pickups.create

Create POP3 pickup source.

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

```ts
openemail.pickups.create(
  mailboxId: string,
  body: PickupsCreateBody,
  options?: CallOptions,
): ApiPromise<PickupSource>
```

It calls `POST /mailboxes/{mailboxId}/pickups`: [Create POP3 pickup source](/docs/api/pickups/post_PickupCreate) in the API reference.

## Example

```ts
const pickupSource = await openemail.pickups.create(mailboxId, {
  host: 'mail.example.com',
  port: 1,
  username: '…',
  password: '…',
})
```

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `mailboxId` | `string` | Mailbox ULID identifier. The path's `{mailboxId}`. |
| `body` | [`PickupsCreateBody`](#pickupscreatebody) | 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](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

Awaited, it is the API's JSON, [`PickupSource`](/docs/sdks/typescript/types/pickup-source). It is an [`ApiPromise`](/docs/sdks/typescript/responses): `.withResponse()` gives the same with the `Response` it came in, for its headers.

## Errors

| Status | What it means |
| --- | --- |
| `400` | validation_failed; or source_is_self when the credentials would open the very mailbox this source delivers into. Pulling from ANOTHER mailbox on this platform is supported |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `404` | Mailbox not found or not accessible |
| `409` | duplicate_source — same host and username already configured for this mailbox; pickup_limit_reached — the mailbox already holds the maximum number of sources (`limit` says how many), a ceiling rather than a rate, so it is not retried; or conflict — destination preparation expired or is unavailable, so retry |
| `413` | too_large: JSON request body exceeds 1 MiB or 500,000 values (object keys included), checked before parsing |
| `503` | pickup_not_configured — this deployment has no PICKUP_KEK, so a source password cannot be stored. 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`](/docs/sdks/typescript/errors): its `status`, and its `code`, the API's `error`. Decide on the code: one status covers several.

## Types

### PickupsCreateBody

```ts
/** The body of `pickups.create`. */
type PickupsCreateBody = {
  deleteAfterFetch?: boolean
  host: string
  intervalMinutes?: number
  labelName?: string
  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')
  name?: string
  password: string
  port: number
  /** Days without a newly stored message, after a drained run, that complete an import (default 7) */
  quietDays?: number
  tls?: ('tls' | 'starttls')
  username: string
}
```

It names these types of the API, each on a page of its own: [`PickupSource`](/docs/sdks/typescript/types/pickup-source).
