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

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, or delete credentials. It can rotate only its own password, and only when self-service allows it.

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": "[e-mail]",
      "accessMode": "read_write",
      "sendingMode": "identity",
      "sendingName": "Support",
      "sendingAddress": "[e-mail]",
      "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": "[e-mail]"
        }
      ],
      "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:

{
  "id": "YOUR_MAILBOX_ID",
  "loginAddress": "[e-mail]",
  "accessMode": "read_write",
  "sendingMode": "identity",
  "sendingName": "Support",
  "sendingAddress": "[e-mail]",
  "allowedSendingDomains": [],
  "scopes": [
    { "type": "address", "domain": "example.com", "address": "[e-mail]" }
  ],
  "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.

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": "[e-mail]",
    "accessMode": "read_write",
    "sendingMode": "identity",
    "sendingName": "Support",
    "sendingAddress": "[e-mail]",
    "scopes": [
      {
        "type": "address",
        "domainId": "YOUR_DOMAIN_ID",
        "address": "[e-mail]"
      }
    ]
  }'

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.

A successful creation returns HTTP 201:

{
  "data": {
    "id": "YOUR_MAILBOX_ID",
    "name": "Support inbox",
    "loginAddress": "[e-mail]"
  },
  "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": {...}}.

​

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.

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 for how each one works.

​

Disable or re-enable access

Disable

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

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

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.

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.

​

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

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.

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.