# Mailbox routes: rest, retire, warm

URL: /code/api/mailbox/verbs · Id: `page:code/api/mailbox/verbs`

> The Mailbox Verbs rest, retire, warm as api.sb routes, with inputs, result, refusals and an example.

Reference for [Mailbox](/business/nouns/mailbox), one group of [Mailbox routes](/code/api/mailbox).

### Mailbox.rest
Rest pauses a Mailbox’s sending when a brake fires and resumes it when the reading clears. [Verb page](/business/nouns/mailbox/rest?interface=api).

```text
POST /{namespace}/mailboxes/{mailbox}/rest
```

Path: `mailbox`. Body, as JSON: the other inputs. Emits [`Mailbox.rested`](/business/events/Mailbox.rested).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `mailbox` | [Mailbox](/business/nouns/mailbox) | Yes | The Mailbox to pause. |
| `reason` | `string` | Yes | The brake that fired. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `mailbox` | [Mailbox](/business/nouns/mailbox) | Yes | The Mailbox, resting. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```bash
curl -X POST https://api.sb/leaseline.app/mailboxes/mailbox_93HvOnR17L/rest \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"complaints"}'
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "mailbox": {
    "$id": "https://api.sb/leaseline.app/mailboxes/mailbox_93HvOnR17L",
    "$type": "Mailbox",
    "medium": "email",
    "address": "dana@leaseline.app",
    "stream": "transactional"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Mailbox.rest",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### Mailbox.retire
Retire stops a Mailbox for good and keeps its address, Messages and sending history. [Verb page](/business/nouns/mailbox/retire?interface=api).

```text
POST /{namespace}/mailboxes/{mailbox}/retire
```

Path: `mailbox`. Emits [`Mailbox.retired`](/business/events/Mailbox.retired).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `mailbox` | [Mailbox](/business/nouns/mailbox) | Yes | The Mailbox to retire. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `mailbox` | [Mailbox](/business/nouns/mailbox) | Yes | The retired Mailbox. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```bash
curl -X POST https://api.sb/leaseline.app/mailboxes/mailbox_93HvOnR17L/retire \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY"
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "mailbox": {
    "$id": "https://api.sb/leaseline.app/mailboxes/mailbox_93HvOnR17L",
    "$type": "Mailbox",
    "medium": "email",
    "address": "dana@leaseline.app",
    "stream": "transactional"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Mailbox.retire",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```

### Mailbox.warm
Warm ramps a new Mailbox from a few sends a day to its cap over two to four weeks. [Verb page](/business/nouns/mailbox/warm?interface=api).

```text
POST /{namespace}/mailboxes/{mailbox}/warm
```

Path: `mailbox`. Body, as JSON: the other inputs. Emits [`Mailbox.warmed`](/business/events/Mailbox.warmed).

**Inputs**

| Input | Type | Required | Description |
| --- | --- | --- | --- |
| `mailbox` | [Mailbox](/business/nouns/mailbox) | Yes | The new Mailbox. |
| `cap` | `integer` | Yes | The daily sends it ramps to. |

**Returns**

| Output | Type | Required | Description |
| --- | --- | --- | --- |
| `mailbox` | [Mailbox](/business/nouns/mailbox) | Yes | The Mailbox, warming. |

**Refuses when**

| Check | Error | Fix | Then call |
| --- | --- | --- | --- |
| The key is valid, but its scopes do not allow this operation. | [`forbidden`](/code/api/errors/forbidden) | Use a key whose scopes cover the operation, or ask an owner of the namespace to grant them. | None. |

**Example**

```bash
curl -X POST https://api.sb/leaseline.app/mailboxes/mailbox_93HvOnR17L/warm \
  -H "Authorization: Bearer $STARTUP_BUILDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"cap":1}'
```

```json
{
  "api": "https://api.sb/leaseline.app",
  "mailbox": {
    "$id": "https://api.sb/leaseline.app/mailboxes/mailbox_93HvOnR17L",
    "$type": "Mailbox",
    "medium": "email",
    "address": "dana@leaseline.app",
    "stream": "transactional"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/act_br07HsG8MG",
    "operation": "Mailbox.warm",
    "status": "done"
  },
  "links": {
    "self": "https://api.sb/leaseline.app/actions/act_br07HsG8MG"
  }
}
```