helpscout api 'mailbox not found'
Fix Helpdesk's 'mailbox not found' (Help Scout): the mailbox id in your API call doesn't exist under the credentials you're using. Use when Help Scout API calls fail with mailbox not found, when the mailbox works in the UI but not the API, or when calls fail after a mailbox rename or permission change. Not for authentication errors, conversation API errors, or webhook issues.
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
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