## mailboxes : object
Add, modify, and delete mailboxes and mailbox customers.
**Kind**: global namespace
* [mailboxes](#mailboxes) : object
* [.FormPS1583](#mailboxes.FormPS1583)
* [new FormPS1583()](#new_mailboxes.FormPS1583_new)
* [.getList(filter)](#mailboxes.getList) ⇒ Promise.<Array>
* [.addDaysToMailbox(boxNumber, days, months)](#mailboxes.addDaysToMailbox) ⇒ Promise
* [.setMailboxExpirationDate(boxNumber, date)](#mailboxes.setMailboxExpirationDate) ⇒ Promise
* [.createMailbox(number, size, notes, barcode)](#mailboxes.createMailbox) ⇒ Promise
* [.editMailbox(oldNumber, newNumber, newSize, barcode)](#mailboxes.editMailbox) ⇒ Promise
* [.deleteMailbox(number)](#mailboxes.deleteMailbox) ⇒ Promise
* [.closeMailbox(number)](#mailboxes.closeMailbox) ⇒ Promise
* [.mailboxExists(number)](#mailboxes.mailboxExists) ⇒ Promise.<boolean>
* [.addOrUpdateBoxholder(boxNumber, info)](#mailboxes.addOrUpdateBoxholder) ⇒ Promise
* [.removeBoxholder(boxNumber, uuid)](#mailboxes.removeBoxholder) ⇒ Promise
* [.get1583(boxNumber, uuid, archiveNumber)](#mailboxes.get1583) ⇒ Promise.<FormPS1583>
* [.set1583(boxNumber, uuid, formps1583)](#mailboxes.set1583) ⇒ Promise
* [.boxNumberValid()](#mailboxes.boxNumberValid) ⇒ boolean
* [.getMailboxProducts()](#mailboxes.getMailboxProducts) ⇒ Promise.<Array>
### mailboxes.FormPS1583
**Kind**: static class of [mailboxes](#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](#mailboxes)
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| filter | null \| object | 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](#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](#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](#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](#mailboxes)
| Param | Type | Default | Description |
| --- | --- | --- | --- |
| oldNumber | string | | Currently assigned box number. |
| newNumber | string | | New box number. Must not exist yet. |
| newSize | number \| null | 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](#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](#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](#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](#mailboxes)
| Param | Type | Description |
| --- | --- | --- |
| boxNumber | string | Mailbox number |
| info | Object | Boxholder information. |
**Example**
```js
// 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](#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](#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](#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)
### mailboxes.getMailboxProducts() ⇒ Promise.<Array>
Get a list of merchandise items that are usable for mailbox renewals.
**Kind**: static method of [mailboxes](#mailboxes)
**Example**
```js
[{
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
}]
```