# Inbound Mail Items
> Inbound Mail Items represent pieces of physical mail delivered to a Lockbox.

[Events](https://increase.com/documentation/events.md) will be generated for this resource. The possible event categories are: `inbound_mail_item.created` and `inbound_mail_item.updated`.

## The Inbound Mail Item object
### Example
```json
{
  "checks": [
    {
      "amount": 1750,
      "back_file_id": "file_makxrc67oh9l6sg7w9yc",
      "check_deposit_id": "check_deposit_f06n9gpg7sxn8t19lfc1",
      "front_file_id": "file_makxrc67oh9l6sg7w9yc",
      "status": "deposited"
    },
    {
      "amount": 1750,
      "back_file_id": "file_makxrc67oh9l6sg7w9yc",
      "check_deposit_id": "check_deposit_f06n9gpg7sxn8t19lfc1",
      "front_file_id": "file_makxrc67oh9l6sg7w9yc",
      "status": "deposited"
    }
  ],
  "created_at": "2020-01-31T23:59:59Z",
  "file_id": "file_makxrc67oh9l6sg7w9yc",
  "id": "inbound_mail_item_q6rrg7mmqpplx80zceev",
  "lockbox_id": "lockbox_3xt21ok13q19advds4t5",
  "recipient_name": "Ian Crease",
  "rejection_reason": null,
  "status": "processed",
  "type": "inbound_mail_item"
}
```
### Attributes
- `checks` (array of objects)
  The checks in the mail item.

  - `checks.amount` (integer)
    The amount of the check.

  - `checks.back_file_id` (string, nullable)
    The identifier for the File containing the back of the check.

  - `checks.check_deposit_id` (string, nullable)
    The identifier of the Check Deposit if this check was deposited.

  - `checks.front_file_id` (string, nullable)
    The identifier for the File containing the front of the check.

  - `checks.status` (enum, nullable)
    The status of the Inbound Mail Item Check.
    Cases:
    * `pending` (The check is pending processing.)
    * `deposited` (The check has been deposited.)
    * `ignored` (The check has been ignored.)

- `created_at` (string)
  The [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) time at which the Inbound Mail Item was created.

- `file_id` (string)
  The identifier for the File containing the scanned contents of the mail item.

- `id` (string)
  The Inbound Mail Item identifier.

- `lockbox_id` (string, nullable)
  The identifier for the Lockbox that received this mail item. For mail items that could not be processed due to an invalid address, this will be null.

- `recipient_name` (string, nullable)
  The recipient name as written on the mail item.

- `rejection_reason` (enum, nullable)
  If the mail item has been rejected, why it was rejected.
  Cases:
  * `no_matching_lockbox` (The mail item does not match any lockbox.)
  * `no_check` (The mail item does not contain a check.)
  * `lockbox_not_active` (The Lockbox or its associated Account is not active.)

- `status` (enum)
  If the mail item has been processed.
  Cases:
  * `pending` (The mail item is pending processing.)
  * `processed` (The mail item has been processed.)
  * `rejected` (The mail item has been rejected.)

- `type` (string)
  A constant representing the object's type. For this resource it will always be `inbound_mail_item`.

## List Inbound Mail Items
GET /inbound_mail_items

### Example
```curl
curl \
  --url "${INCREASE_URL}/inbound_mail_items" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```

### Query Parameters
- `cursor` (string, optional)
  Return the page of entries after this one.

- `limit` (integer, optional)
  Limit the size of the list that is returned. The default (and maximum) is 100 objects.

- `lockbox_id` (string, optional)
  Filter Inbound Mail Items to ones sent to the provided Lockbox.

- `created_at.after` (string, optional)
  Return results after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `created_at.before` (string, optional)
  Return results before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `created_at.on_or_after` (string, optional)
  Return results on or after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

- `created_at.on_or_before` (string, optional)
  Return results on or before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.

### Returns a Inbound Mail Item List object:
```json
{
  "data": [
    {
      "checks": [
        {
          "amount": 1750,
          "back_file_id": "file_makxrc67oh9l6sg7w9yc",
          "check_deposit_id": "check_deposit_f06n9gpg7sxn8t19lfc1",
          "front_file_id": "file_makxrc67oh9l6sg7w9yc",
          "status": "deposited"
        },
        {
          "amount": 1750,
          "back_file_id": "file_makxrc67oh9l6sg7w9yc",
          "check_deposit_id": "check_deposit_f06n9gpg7sxn8t19lfc1",
          "front_file_id": "file_makxrc67oh9l6sg7w9yc",
          "status": "deposited"
        }
      ],
      "created_at": "2020-01-31T23:59:59Z",
      "file_id": "file_makxrc67oh9l6sg7w9yc",
      "id": "inbound_mail_item_q6rrg7mmqpplx80zceev",
      "lockbox_id": "lockbox_3xt21ok13q19advds4t5",
      "recipient_name": "Ian Crease",
      "rejection_reason": null,
      "status": "processed",
      "type": "inbound_mail_item"
    }
  ],
  "next_cursor": "v57w5d"
}
```

## Retrieve an Inbound Mail Item
GET /inbound_mail_items/{inbound_mail_item_id}

### Example
```curl
curl \
  --url "${INCREASE_URL}/inbound_mail_items/inbound_mail_item_q6rrg7mmqpplx80zceev" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}"
```
### Path Parameters
- `inbound_mail_item_id` (string, required)
  The identifier of the Inbound Mail Item to retrieve.

## Action an Inbound Mail Item
POST /inbound_mail_items/{inbound_mail_item_id}/action

### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/inbound_mail_items/inbound_mail_item_q6rrg7mmqpplx80zceev/action" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "checks": [
      {
        "account_id": "account_in71c4amph0vgo2qllky",
        "action": "deposit"
      },
      {
        "action": "ignore"
      }
    ]
  }'
```
### Path Parameters
- `inbound_mail_item_id` (string, required)
  The identifier of the Inbound Mail Item to action.

### Body Parameters
- `checks` (array of objects, required)
  The actions to perform on the Inbound Mail Item.

  - `checks.account_id` (string, optional)
    The identifier of the Account to deposit the check into. If not provided, the check will be deposited into the Account associated with the Lockbox.

  - `checks.action` (enum, required)
    The action to perform on the Inbound Mail Item.
    Cases:
    * `deposit` (The check will be deposited.)
    * `ignore` (The check will be ignored.)

## Sandbox: Create an Inbound Mail Item
POST /simulations/inbound_mail_items
> Simulates an inbound mail item to your account, as if someone had mailed a physical check to one of your account's Lockboxes.
### Example
```curl
curl -X "POST" \
  --url "${INCREASE_URL}/simulations/inbound_mail_items" \
  -H "Authorization: Bearer ${INCREASE_API_KEY}" \
  -H "Content-Type: application/json" \
  -d $'{
    "amount": 1000,
    "lockbox_id": "lockbox_3xt21ok13q19advds4t5"
  }'
```

### Body Parameters
- `amount` (integer, required)
  The amount of the check to be simulated, in cents.

- `contents_file_id` (string, optional)
  The file containing the PDF contents. If not present, a default check image file will be used.

- `lockbox_id` (string, required)
  The identifier of the Lockbox to simulate inbound mail to.