Skip to content

# Mailboxes

## mailboxes : `object`

Add, modify, and delete mailboxes and mailbox customers.

Kind: global namespace

- mailboxes : `object`
  - .FormPS1583
    - new FormPS1583()
  - .getList(filter) ⇒ `Promise.<Array>`
  - .addDaysToMailbox(boxNumber, days, months) ⇒ `Promise`
  - .setMailboxExpirationDate(boxNumber, date) ⇒ `Promise`
  - .createMailbox(number, size, notes, barcode) ⇒ `Promise`
  - .editMailbox(oldNumber, newNumber, newSize, barcode) ⇒ `Promise`
  - .deleteMailbox(number) ⇒ `Promise`
  - .closeMailbox(number) ⇒ `Promise`
  - .mailboxExists(number) ⇒ `Promise.<boolean>`
  - .addOrUpdateBoxholder(boxNumber, info) ⇒ `Promise`
  - .removeBoxholder(boxNumber, uuid) ⇒ `Promise`
  - .get1583(boxNumber, uuid, archiveNumber) ⇒ `Promise.<FormPS1583>`
  - .set1583(boxNumber, uuid, formps1583) ⇒ `Promise`
  - .boxNumberValid() ⇒ `boolean`
  - .getMailboxProducts() ⇒ `Promise.<Array>`

### mailboxes.FormPS1583

Kind: static class of `mailboxes`

#### new FormPS1583()

USPS Form PS1583 object, with all the fields needed by USPS for CMRA customers.

### mailboxes.getList(filter) ⇒ `Promise.<Array>`

Get the list of mailboxes and boxholders as an array of objects, see example.

Kind: static method of `mailboxes`

Param | Type | Default | Description
--- | --- | --- | ---

filter

`null` | `object`

``

Filter to mailboxes matching a column condition, such as `getList({number: "102"})` or `getList({"size >=": "2"})`. Supported filter names include "number" (string, box number), "expires" (expiration date), "size" (number 1-10), and "barcode" (string) SQL injection warning: Filter names are inserted directly into query strings without sanitization. Only the values are safe for user input.

Example

    [{
        num: "123", // Box number as string
        expires: 1234567890, // UNIX timestamp (in seconds) or false if box vacant
        size: "2", // Box size, 1-10
        notes: "", // Notes for mailbox, not currently shown in Mailbox Manager UI but may be used in the future
        barcode: "", // Unique barcode for the mailbox, for future use
        renewalMerchID: "", // Merchandise item ID used for autorenewing this mailbox
        isBusiness: false, // True if the box is for a business, false if for personal use
        names: [], // Array of boxholders. See addOrUpdateBoxholder for the format.
        packages: [], // Array of packages awaiting pickup, see below
        vacant: false // True if the box is currently vacant, else false
    }]

Example

    // Data objects in the packages array:
    {
        tracking: tracking ?? "[Untracked]", // Package tracking number
        finalized: true, // True if package check-in is finished and shelf tag/mailbox slips printed, false if not finalized
        available_date: Date(), // The date and time the package was checked in
        tag: "" // Unique number assigned to the package and printed on shelf tags, scanned by employee when customer picks up package
    }

### mailboxes.addDaysToMailbox(boxNumber, days, months) ⇒ `Promise`

Add a number of days or months to a mailbox's expiration. Use either days or months, not both.

Kind: static method of `mailboxes`

Param | Type | Default | Description
--- | --- | --- | ---
boxNumber | `string` |  | Mailbox number.
days | `number` | `0` | Days to add.
months | `number` | `0` | Months to add.

### mailboxes.setMailboxExpirationDate(boxNumber, date) ⇒ `Promise`

Set the box expiration to a specific JavaScript Date object, or a UNIX timestamp (in seconds).

Kind: static method of `mailboxes`

Param | Type
--- | ---
boxNumber | `string`
date | `number` | `Date`

### mailboxes.createMailbox(number, size, notes, barcode) ⇒ `Promise`

Create a new mailbox number with the specified box size. Throws an error if the box number is already in use.

Kind: static method of `mailboxes`

Param | Type | Description
--- | --- | ---
number | `string` | Mailbox number
size | `number` | Box size (1 - 10)
notes | `string` | Arbitrary string with human-readable notes about the box.
barcode | `null` | `string` | A barcode value representing this mailbox, typically a sticker on the the physical box visible when delivering mail.

### mailboxes.editMailbox(oldNumber, newNumber, newSize, barcode) ⇒ `Promise`

Change the number and/or size of a mailbox while preserving the boxholders and packages associated. If only changing size, set oldNumber and newNumber to the same value.

Kind: static method of `mailboxes`

Param | Type | Default | Description
--- | --- | --- | ---
oldNumber | `string` |  | Currently assigned box number.
newNumber | `string` |  | New box number. Must not exist yet.
newSize | `number` | `null` | `` | Box size (1 - 10), if changing the size.
barcode | `null` | `string` |  | A barcode value representing this mailbox, typically a sticker on the the physical box visible when delivering mail.

### mailboxes.deleteMailbox(number) ⇒ `Promise`

Delete a mailbox. Throws an Error if the mailbox has boxholders attached.

Kind: static method of `mailboxes`

Param | Type | Description
--- | --- | ---
number | `string` | Mailbox number to delete.

### mailboxes.closeMailbox(number) ⇒ `Promise`

Close a mailbox by removing the boxholders and marking it as vacant. Boxholder PS Form 1583 records are automatically archived per USPS regulations.

Kind: static method of `mailboxes`

Param | Type | Description
--- | --- | ---
number | `string` | Mailbox number to close.

### mailboxes.mailboxExists(number) ⇒ `Promise.<boolean>`

Returns true if the mailbox number exists, false if it doesn't.

Kind: static method of `mailboxes`

Param | Type | Description
--- | --- | ---
number | `string` | Mailbox number to check.

### mailboxes.addOrUpdateBoxholder(boxNumber, info) ⇒ `Promise`

Modify or add a boxholder to a mailbox. info is the boxholder structure below. If the uuid given already belongs to a boxholder, their info is updated with what you supply. Otherwise, the info is added as a new boxholder.

Kind: static method of `mailboxes`

Param | Type | Description
--- | --- | ---
boxNumber | `string` | Mailbox number
info | `Object` | Boxholder information.

Example

    // Unless noted, all fields are strings and default to an empty string.
    {
        name: [bizname, fname, mname, lname].filter(Boolean).join(" "),
        fname: "", // First name
        mname: "", // Middle name
        lname: "", // Last name
        email: "", // Email
        phone: "", // Phone
        uuid: "", // Customer UUID
        bizname: "", // Business name
        street1: "", // Street address
        city: "", // City
        state: "", // Two-character state
        zipcode: "", // ZIP or postal code
        country: "", // Two-character country code
        primary: true // True if the primary (first) boxholder, false if an additional authorized mail recipient
    }

### mailboxes.removeBoxholder(boxNumber, uuid) ⇒ `Promise`

Remove a boxholder by their UUID, and archive their PS Form 1583 data per USPS regulations.

Kind: static method of `mailboxes`

Param | Type | Description
--- | --- | ---
boxNumber | `string` | Mailbox number.
uuid | `string` | Boxholder UUID.

### mailboxes.get1583(boxNumber, uuid, archiveNumber) ⇒ `Promise.<FormPS1583>`

Get the FormPS1583 object for a boxholder by UUID.

Kind: static method of `mailboxes`

Param | Type | Default | Description
--- | --- | --- | ---
boxNumber | `string` |  | Mailbox number.
uuid | `string` |  | Boxholder UUID.
archiveNumber | `boolean` | `false` | If true, returns the form for a deleted boxholder from the archive.

### mailboxes.set1583(boxNumber, uuid, formps1583) ⇒ `Promise`

Set the FormPS1583 object for a boxholder by UUID.

Kind: static method of `mailboxes`

Param | Type | Description
--- | --- | ---
boxNumber | `string` | Mailbox number.
uuid | `string` | Boxholder UUID.
formps1583 | `FormPS1583` | The FormPS1583 object to use.

### mailboxes.boxNumberValid() ⇒ `boolean`

Returns true if the mailbox number is an acceptable format, false if it isn't. Does not check if the box actually exists, merely if the number is acceptable to use as a mailbox number.

Kind: static method of `mailboxes`

### mailboxes.getMailboxProducts() ⇒ `Promise.<Array>`

Get a list of merchandise items that are usable for mailbox renewals.

Kind: static method of `mailboxes`
Example

    [{
        id: "", // Unique ID for this entry in the merchandise table
        name: "", // Merch item name
        category: "", // Merch item category
        price: 0.0, // Sale price in dollars
        cost: 0.0, // Merchandise cost in dollars (likely not used for mailboxes)
        barcode: "", // Barcode/UPC (likely not used for mailboxes)
        tax: 0.0, // Sales tax rate
        rentaldays: 30, // Number of days this item adds to a mailbox (mutually exclusive with rentalmonths)
        rentalmonths: 1, // Number of months (mutually exclusive with rentaldays)
        boxsize: "1" // Mailbox size tier, 1-10
    }]