> ## Documentation Index
> Fetch the complete documentation index at: https://inbound.new/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage Credentials

> Create, update, disable, rotate, and delete managed mailbox and SMTP credentials

Manage mailbox and SMTP credentials from the dashboard or the authenticated REST API. A credential controls one login address, its incoming-mail scopes, its SMTP sender policy, and its enabled state.

## Use the dashboard

**1. Open Mailboxes & SMTP**

Go to [Mailboxes & SMTP](https://inbound.new/mailboxes). You need at least one verified domain before creating a credential.

**2. Create a credential**

Select **Create credential**, then choose **Mailbox + SMTP** or **SMTP only**. Enter a name and login email, select the access level (**Read only** or **Read & write**) when applicable, configure the sender policy, and add at least one domain or address scope.

**3. Store the generated password**

After creation, the dashboard displays the login address, generated password, and applicable connection settings. The password is shown only once.

**4. Manage an existing credential**

Open the credential's actions menu to **Edit**, **Rotate password**, **Disable** or **Enable**, or **Delete** the credential.

> [!WARNING]
>
> A generated mailbox or SMTP password cannot be retrieved after the creation or rotation dialog closes. Store it securely. If you lose it, rotate the password and update every client using that credential.

## Authenticate REST requests

The dashboard uses your authenticated account session. For programmatic REST requests, use an ordinary account API key from [API Keys](https://inbound.new/api-keys), supplied as a Bearer token:

```bash theme={null}
export INBOUND_API_KEY="YOUR_ACCOUNT_API_KEY"
```

> [!WARNING]
>
> Credential-management endpoints require your ordinary account API token. A generated mailbox or SMTP password is for managed mail authentication and cannot be used to list, create, update, or delete credentials. It can rotate only its own password, and only when [self-service](https://inbound.new/docs/mailboxes/access-and-limits.md#self-service) allows it.

All examples use the production API base URL:

```text theme={null}
https://inbound.new/api/e2
```

### Find a verified domain ID

A scope references a verified domain's ID, not just its domain name. Obtain `YOUR_DOMAIN_ID` from the dashboard or list your verified domains:

```bash theme={null}
curl "https://inbound.new/api/e2/domains?status=verified&limit=50" \
  -H "Authorization: Bearer $INBOUND_API_KEY"
```

Use the `id` of the matching domain in the `data` array. When creating or editing a credential definition, its login address must also use an exact owned, verified domain, which does not have to be the same domain as a scope.

## List credentials

```bash theme={null}
curl "https://inbound.new/api/e2/mailboxes?limit=20&offset=0" \
  -H "Authorization: Bearer $INBOUND_API_KEY"
```

A successful response contains the credentials and offset-based pagination metadata:

```json theme={null}
{
  "data": [
    {
      "id": "YOUR_MAILBOX_ID",
      "type": "mailbox",
      "name": "Support inbox",
      "loginAddress": "imap@example.com",
      "accessMode": "read_write",
      "sendingMode": "identity",
      "sendingName": "Support",
      "sendingAddress": "support@example.com",
      "enabled": true,
      "protocols": { "imap": true, "smtp": true, "api": true },
      "allowedIps": [],
      "storageQuotaBytes": null,
      "dailySendLimit": null,
      "selfService": { "filters": false, "spam": false, "password": false },
      "scopes": [
        {
          "id": "SCOPE_ID",
          "type": "address",
          "domainId": "YOUR_DOMAIN_ID",
          "domain": "example.com",
          "address": "support@example.com"
        }
      ],
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z",
      "lastUsedAt": null
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 1,
    "hasMore": false
  }
}
```

`limit` defaults to `50` and cannot exceed `100`. Credentials are listed newest first. Increase `offset` while `pagination.hasMore` is `true`.

### Get one mailbox

`GET /mailboxes/YOUR_MAILBOX_ID` returns a mailbox's identity, scopes, controls and unread `INBOX` count. The mailbox user can call `GET /mailboxes/me` with its own password. This response is not wrapped in `data` and has a different shape from list items:

```json theme={null}
{
  "id": "YOUR_MAILBOX_ID",
  "loginAddress": "imap@example.com",
  "accessMode": "read_write",
  "sendingMode": "identity",
  "sendingName": "Support",
  "sendingAddress": "support@example.com",
  "allowedSendingDomains": [],
  "scopes": [
    { "type": "address", "domain": "example.com", "address": "support@example.com" }
  ],
  "protocols": { "imap": true, "smtp": true, "api": true },
  "allowedIps": [],
  "storageQuotaBytes": null,
  "dailySendLimit": null,
  "selfService": { "filters": false, "spam": false, "password": false },
  "unreadCount": 0,
  "authenticatedAs": "account"
}
```

`allowedSendingDomains` lists the domains a `scoped_domains` credential can send from. `authenticatedAs` is `account` for an account API key and `mailbox` for the mailbox password. SMTP only credentials have no mailbox, so this endpoint returns `400` for them.

## Create a credential

`POST /mailboxes` requires every top-level field shown below, including `sendingName` and `sendingAddress`; nullable values must still be included. Provide between 1 and 100 unique scopes. Accounts can create up to 100 managed credentials by default.

```bash theme={null}
curl -X POST "https://inbound.new/api/e2/mailboxes" \
  -H "Authorization: Bearer $INBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mailbox",
    "name": "Support inbox",
    "loginAddress": "imap@example.com",
    "accessMode": "read_write",
    "sendingMode": "identity",
    "sendingName": "Support",
    "sendingAddress": "support@example.com",
    "scopes": [
      {
        "type": "address",
        "domainId": "YOUR_DOMAIN_ID",
        "address": "support@example.com"
      }
    ]
  }'
```

Replace `YOUR_DOMAIN_ID` with the verified domain ID returned by `GET /domains`.

You can also set `protocols`, `allowedIps`, `storageQuotaBytes`, `dailySendLimit` and `selfService` when creating the credential. They are optional: left out, every protocol is on, any IP address is allowed, there is no per-credential quota or send limit, and self-service is off. See [Access and Limits](https://inbound.new/docs/mailboxes/access-and-limits.md).

A successful creation returns HTTP `201`:

```json theme={null}
{
  "data": {
    "id": "YOUR_MAILBOX_ID",
    "name": "Support inbox",
    "loginAddress": "imap@example.com"
  },
  "password": "YOUR_GENERATED_MAIL_PASSWORD"
}
```

The real `data` object includes the complete credential fields shown in the list response. `password` appears only in this creation response.

For a domain-wide scope, use `{"type":"domain","domainId":"YOUR_DOMAIN_ID"}`. For `sendingMode: "scoped_domains"`, provide `"sendingName": null` and `"sendingAddress": null`. SMTP-only credentials use `"type": "smtp"`; `accessMode` is still required in the request and is normalized to `read_write` in responses.

> [!NOTE]
>
> An address scope plus `scoped_domains` allows sending from any address on that exact domain. See [scopes and permissions](https://inbound.new/docs/mailboxes/scopes-and-permissions.md#any-scoped-domain) before choosing a sender policy.

## Update a credential

`PUT /mailboxes/:id` accepts a partial JSON object. Omitted fields retain their existing values.

```bash theme={null}
curl -X PUT "https://inbound.new/api/e2/mailboxes/YOUR_MAILBOX_ID" \
  -H "Authorization: Bearer $INBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer support",
    "accessMode": "read"
  }'
```

To change scopes, provide the complete replacement scope list:

```bash theme={null}
curl -X PUT "https://inbound.new/api/e2/mailboxes/YOUR_MAILBOX_ID" \
  -H "Authorization: Bearer $INBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scopes": [
      {
        "type": "domain",
        "domainId": "YOUR_DOMAIN_ID"
      }
    ]
  }'
```

The resulting configuration must remain valid. For example, an exact sending identity must still be covered by the replacement scopes. Successful updates return `{"data": {...}}`.

### Restrict access and set limits

Use the same endpoint to turn protocols off, allow only certain IP ranges, cap storage and daily sends, or let the mailbox user manage filters, spam settings or their password. `protocols` and `selfService` merge key by key, so `{"protocols":{"api":false}}` changes only `api`. Set a field to `null` to reset it to its default.

```bash theme={null}
curl -X PUT "https://inbound.new/api/e2/mailboxes/YOUR_MAILBOX_ID" \
  -H "Authorization: Bearer $INBOUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocols": { "imap": true, "smtp": true, "api": false },
    "allowedIps": ["203.0.113.0/24"],
    "dailySendLimit": 500,
    "selfService": { "filters": true, "spam": true, "password": false }
  }'
```

Only an account API key or the dashboard can change these fields. See [Access and Limits](https://inbound.new/docs/mailboxes/access-and-limits.md) for how each one works.

### Disable or re-enable access

> [tab] Disable
>
> ```bash theme={null}
> curl -X PUT "https://inbound.new/api/e2/mailboxes/YOUR_MAILBOX_ID" \
>   -H "Authorization: Bearer $INBOUND_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"enabled": false}'
> ```

> [tab] Re-enable
>
> ```bash theme={null}
> curl -X PUT "https://inbound.new/api/e2/mailboxes/YOUR_MAILBOX_ID" \
>   -H "Authorization: Bearer $INBOUND_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"enabled": true}'
> ```

Disabling prevents new IMAP, SMTP and HTTP use of the password, and the account's mailbox API calls for it return `403` with `Mailbox is disabled`. The credential, its folders, drafts, sent copies, flags, and other mailbox state are kept. Re-enabling preserves the existing password unless you also rotate it.

## Rotate a password

```bash theme={null}
curl -X POST \
  "https://inbound.new/api/e2/mailboxes/YOUR_MAILBOX_ID/rotate-password" \
  -H "Authorization: Bearer $INBOUND_API_KEY"
```

A successful response contains only the newly generated password:

```json theme={null}
{
  "password": "YOUR_NEW_MAIL_PASSWORD"
}
```

The previous password stops working immediately. The replacement is shown only in this response, so update every IMAP and SMTP client that uses the credential.

When the credential's `selfService.password` is enabled, the mailbox user can rotate it with their current password at `POST /mailboxes/me/rotate-password`. See [Access and Limits](https://inbound.new/docs/mailboxes/access-and-limits.md#self-service).

## Delete a credential

```bash theme={null}
curl -X DELETE "https://inbound.new/api/e2/mailboxes/YOUR_MAILBOX_ID" \
  -H "Authorization: Bearer $INBOUND_API_KEY"
```

A successful response is:

```json theme={null}
{
  "success": true
}
```

> [!WARNING]
>
> Deletion permanently removes the credential and its credential-specific IMAP folders, drafts, saved sent copies, flags, and locally appended mailbox data. This mailbox state cannot be restored by creating another credential. Disable the credential instead when access should be suspended without losing its state.

## Active sessions and errors

Changes to authentication or permissions, including login addresses, access modes, sender settings, scopes, enabled state, password rotation, `protocols`, `allowedIps` and `selfService`, immediately log out active IMAP sessions for that credential. Clients must reconnect using the current credential settings. Deletion also invalidates active IMAP sessions. See [Access and Limits](https://inbound.new/docs/mailboxes/access-and-limits.md#allowed-ip-addresses).

A domain verification-status change is different: it affects which scope domains are accepted during subsequent authentication, but does not automatically terminate an established IMAP session. Disable or edit the credential, or rotate its password, when existing sessions must be ended.

| HTTP status | Meaning | Recommended action |
| - | - | - |
| `400` | A missing or invalid field (`Validation failed`), or an invalid scope, login email or sender identity | Correct the request and verify exact domain ownership |
| `401` | Missing or invalid ordinary account API token | Use a valid account API key, not a managed mail password |
| `403` | The account cannot perform the request or has reached its credential limit (`Mailbox limit reached (100)`) | Check account access and delete unused credentials if necessary |
| `404` | The credential does not exist or is not owned by your account | Confirm `YOUR_MAILBOX_ID` |
| `409` | The login address is already assigned, or the credential changed during password rotation | Choose a unique login address or retry the password rotation |
| `429` | Account API rate limit exceeded | Wait for the `Retry-After` interval before retrying |
| `503` | A required request-protection service is temporarily unavailable | Honor `Retry-After` and retry later |

Credential-management requests share the account API limit, which defaults to 100 requests per second. See [API rate limits](https://inbound.new/docs/api-reference/rate-limits.md).

> [card] [Scopes and Permissions](https://inbound.new/docs/mailboxes/scopes-and-permissions.md)
>
> Choose the right incoming scopes, IMAP access mode, and sender policy.

> [card] [Connect with IMAP](https://inbound.new/docs/mailboxes/connect-imap.md)
>
> Read mail over IMAP using your generated login and password.

> [card] [Send with SMTP](https://inbound.new/docs/mailboxes/connect-smtp.md)
>
> Send mail over SMTP using the same credential.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.