GET /v1/attachments/:id
Download the raw bytes of an attachment someone sent you.
GET /v1/attachments/{id}Returns the raw bytes of one inbound attachment. Ids come from the
attachmentIds array on a message event.
This endpoint is download-only. There is currently no way to upload media, which is why the
attachment and sticker send payloads cannot be used yet.
Request
curl -O -J \
$MAPIER_BASE_URL/v1/attachments/8f2c1a4e-... \
-H "Authorization: Bearer $MAPIER_API_KEY"The path accepts the id and nothing else — no sub-paths, no query string. A
request with either returns 404.
Conditional requests
Pass the etag you stored previously to skip re-downloading:
If-None-Match: "9f3c...64hex"A match returns 304 Not Modified with no body.
Response
HTTP/1.1 200 OK
content-type: image/heic
content-length: 1048576
etag: "9f3c...64hex"
cache-control: private, max-age=31536000, immutable
content-disposition: inline; filename="IMG_0421.heic"Prop
Type
Files are served as sent. iPhone photos commonly arrive as HEIC, which browsers other than Safari cannot display. Convert server-side if you need to render them.
Lifetime and access
The URL is permanent and unsigned — it is not a presigned link that expires. Access is controlled by your credential on every request, so the URL is safe to store but not safe to hand to a browser or a third party as-is.
An attachment belonging to another account returns 404, identical to one that
does not exist. Existence is never leaked.
An attachment that has not finished transferring also returns 404; retry
shortly.
Unconfirmed
No maximum download size is surfaced to callers. The underlying limit is declared by the Mac and not exposed, so stream large responses rather than buffering them if you cannot bound the size.
Errors
| Status | Code | Cause |
|---|---|---|
400 | invalid_id | The id could not be decoded |
401 | unauthenticated | No credential |
404 | not_found | Unknown attachment, another account's, or not yet available |
405 | method_not_allowed | Not a GET |
429 | rate_limited | 120 requests per minute |