Skip to content

Mailboxes

mailboxes : object

Add, modify, and delete mailboxes and mailbox customers.

Kind: global namespace

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
}]