Manage 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

Open Mailboxes & SMTP

Go to Mailboxes & SMTP. You need at least one verified domain before creating a credential.

Create 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.

Store the generated password

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

Manage an existing credential

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, supplied as a Bearer token:

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:

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:

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

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:

{
  "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.

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:

{
  "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 before choosing a sender policy.

Update a credential

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

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:

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

Disable
Re-enable

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}'

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

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:

{
  "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

curl -X DELETE "https://inbound.new/api/e2/mailboxes/YOUR_MAILBOX_ID" \
  -H "Authorization: Bearer $INBOUND_API_KEY"

A successful response is:

{
  "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.

Scopes and Permissions

Choose the right incoming scopes, IMAP access mode, and sender policy.

Connect with IMAP

Read mail over IMAP using your generated login and password.

Send with SMTP

Send mail over SMTP using the same credential.

Quickstart

Mailboxes & SMTP

Integrations

Manage Credentials

Use the dashboard

Authenticate REST requests

Find a verified domain ID

List credentials

Create a credential

Update a credential

Disable or re-enable access

Rotate a password

Delete a credential

Active sessions and errors

Scopes and Permissions

Connect with IMAP

Send with SMTP

​Use the dashboard

​Authenticate REST requests

​Find a verified domain ID

​List credentials

​Create a credential

​Update a credential

​Disable or re-enable access

​Rotate a password

​Delete a credential

​Active sessions and errors

Scopes and Permissions

Connect with IMAP

Send with SMTP

Use the dashboard

Authenticate REST requests

Find a verified domain ID

List credentials

Create a credential

Update a credential

Disable or re-enable access

Rotate a password

Delete a credential

Active sessions and errors