> ## 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
Go to [Mailboxes & SMTP](https://inbound.new/mailboxes). You need at least one verified domain before creating a credential.
Select **Create credential**, then choose **Mailbox + SMTP** or **SMTP only**. Enter a name and login email, select the IMAP access level when applicable, configure the sender policy, and add at least one domain or address scope.
After creation, the dashboard displays the login address, generated password, and applicable connection settings. The password is shown only once.
Open the credential's actions menu to **Edit**, **Rotate password**, **Disable** or **Enable**, or **Delete** the credential.
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"
```
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, rotate, or delete credentials.
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,
"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`. Increase `offset` while `pagination.hasMore` is `true`.
## 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`.
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.
An address scope plus `scoped_domains` allows sending from any address on that exact domain. See [scopes and permissions](/docs/mailboxes/scopes-and-permissions#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": {...}}`.
### Disable or re-enable access
```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}'
```
```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 and SMTP authentication while preserving the credential, its folders, drafts, sent copies, flags, and other mailbox state. 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.
## 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
}
```
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, and password rotation, cause active IMAP sessions for that credential to be logged out. Clients must reconnect using the current credential settings. Deletion also invalidates active IMAP sessions.
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` | Invalid credential configuration, scope, 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 | 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 10 requests per second. See [API rate limits](/docs/api-reference/rate-limits).
Choose the right incoming scopes, IMAP access mode, and sender policy.
Read mail over IMAP using your generated login and password.
Send mail over SMTP using the same credential.