## TL;DR
Help Scout mailboxes are numeric ids, and the API checks them against the authenticated user's access. 'Mailbox not found' means the id is wrong, the mailbox was deleted or renamed, or the API credential's user lost access to it. List the mailboxes with your credential and use an id from that list.

## The query

```text
helpscout api 'mailbox not found'
```

## Use this when

- Help Scout API calls fail with 'mailbox not found'
- The mailbox works in the UI but fails through the API
- Calls fail after a mailbox rename or permission change


## Not for

- Help Scout API authentication errors
- Conversation API errors
- Help Scout webhook issues


## Steps

### 1. List mailboxes with your API credential

Call the mailbox list endpoint with the exact credential your integration uses. If your mailbox id isn't in the response, the credential can't see it. This one call separates wrong-id from wrong-access.

Expected output: the mailbox list as your credential sees it.

### 2. Copy the numeric id, not the name

The UI shows mailbox names; the API wants the numeric id. Copy it from the mailbox list response or the mailbox settings URL. Names get renamed; ids don't.

Expected output: the numeric mailbox id from an API response.

### 3. Check the credential user's permissions

API credentials act as a user, and that user needs access to the mailbox. If an admin removed the user from the mailbox team, the mailbox vanishes from the API while still working for other users in the UI.

Expected output: the credential's user listed on the mailbox's team.

### 4. Audit renames and deletions

If the id used to work, check whether the mailbox was deleted, merged, or had its access changed. Help Scout's activity logs show mailbox changes with timestamps.

Expected output: the change that broke it, or confirmation nothing changed.

## Variant phrasings

### helpscout mailbox id api

Steps 1 and 2: list first, then use the numeric id.

### helpscout api 404 mailbox

Step 3's permission check explains UI-works-API-fails.

## Why it happens

Help Scout ties API visibility to the credential's user, so 'not found' often means 'not visible to you' rather than 'doesn't exist'. On top of that, the UI trains everyone to think in mailbox names while the API thinks in numeric ids. Two different mismatches, one error message.

## Edge cases

- OAuth apps and API keys may see different mailbox sets. Test with the production credential type.
- Mailbox ids are stable across renames. If the id stopped working, something else changed.
- Deleted mailboxes keep their conversations but lose API addressability. Plan migrations before deleting.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Mw8ryDOITk2IpVahGBkK3A