docs: document mailbox attachment download URLs#15
Conversation
Update the attachment guide, product changelog, OpenAPI app snapshot, and generated mailbox Postman collection for short-lived mailbox attachment download URLs.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ab89d5ccc0
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| The `download_url` is short-lived and grants access only to that attachment. Fetch it promptly with any HTTP client; no `Authorization` header is needed for the URL itself. | ||
|
|
||
| If the URL expires, call the message or attachment metadata endpoint again to get a fresh `download_url`. The authenticated attachment download endpoint continues to work for clients that send bearer credentials. |
There was a problem hiding this comment.
When a short-lived URL expires, this tells users to call an “attachment metadata endpoint”, but the OpenAPI paths in this repo only expose /mailbox/attachments:upload and the binary GET /mailbox/messages/{message_id}/attachments/{attachment_id} for attachments, not a metadata endpoint. In that expiration scenario, clients following the guide have no actionable HTTP endpoint to call except re-reading message metadata, so the wording should either name the actual message metadata endpoint or add/document the missing attachment metadata endpoint.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
@chatgpt-codex-connector[bot] Fixed in 320c7dc. The guide now names concrete renewal paths: GET /mailbox/messages/{message_id}, list/search messages again, or MCP mailbox_get_attachment.
There was a problem hiding this comment.
To use Codex here, create an environment for this repo.
| "in": "query", | ||
| "name": "download_token", | ||
| "required": false, | ||
| "schema": { | ||
| "description": "Short-lived token embedded in attachment metadata `download_url` values. Clients normally fetch the full URL rather than constructing this parameter manually.", | ||
| "type": "string" | ||
| } |
There was a problem hiding this comment.
Adding download_token here advertises the same no-Authorization download URL described in the guide, but the operation still declares only bearerAuth while the root spec also requires bearer auth. Generated docs/clients will therefore continue to mark this request as requiring an Authorization header even when the caller supplies the short-lived token, which breaks the documented clients that cannot add that header; model the token path as an alternate/anonymous security option or separate scheme.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
@chatgpt-codex-connector[bot] Fixed in 320c7dc. The OpenAPI operation now allows bearer auth or presigned URL fetch via optional operation security, while keeping download_token as the documented query parameter.
There was a problem hiding this comment.
To use Codex here, create an environment for this repo.
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
roshanjonah
force-pushed
the
agent/attachments-first-class
branch
from
ddd4a89 to
488051c
Compare
1 participant
Update the attachment guide, product changelog, OpenAPI app snapshot, and generated mailbox Postman collection for short-lived mailbox attachment download URLs.