Get attachment metadata
Returns metadata for one email attachment by attachmentId — its filename, contentType, sizeBytes, contentId, disposition, and createdAt, plus the messageId it belongs to.
Returns metadata for one email attachment by attachmentId — its filename, contentType, sizeBytes, contentId, disposition, and createdAt, plus the messageId it belongs to. This endpoint returns metadata only, never the bytes or a URL: fetch a short-lived download link from the /url or /link sub-resource, or stream the raw bytes from /download. attachmentId is the UUID exposed as a message's attachments[].id; a malformed id returns 400 and an attachment your key can't reach returns 404. As the owner you can read metadata whether or not the file has finished its security scan, but a file the scan has flagged as unsafe is withheld with 403. Requires the messages:read scope; see handling untrusted attachments.
Scope: messages:read. Send the API key as a bearer token; Scopes lists what each one reaches.
Request
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
attachmentId | string | yes | The attachment's ID. |
Response
200 Success. Body: application/json, MessageAttachment.
| Field | Type | Required | Description |
|---|---|---|---|
id | string (uuid) | yes | |
filename | string or null | no | |
contentType | string or null | no | |
sizeBytes | integer or null | no | (minimum 0) |
contentId | string or null | no | |
createdAt | string (date-time) or null | no | |
messageId | string (uuid) | no | |
disposition | "attachment", "inline", null | no |
Errors
Every error has the same body, {"error": {"type", "code", "message", "param"}}; branch on code. Errors lists every code.
| Status | Meaning |
|---|---|
400 | The request is malformed or a value is invalid (invalid_request, invalid_domain, idempotency_key_mismatch). |
401 | The API key is missing or invalid. |
403 | The key lacks the scope this endpoint needs (scope_missing) or may not do this (not_permitted). |
404 | No such resource in this account (resource_not_found). |
429 | Rate limit, plan limit, budget or spend cap reached (rate_limited, plan_limit_reached, budget_exceeded, spend_cap_reached). |
500 | An unexpected error; retry with backoff, then contact support (internal_error). |