Skip to content
API Docs
V2 (Legacy) API ReferenceGet started
API Reference

Attachments

Send files (images, videos, documents, audio) with messages by providing a URL in a media part. Pre-uploading via POST /v3/attachments is optional and only needed for specific optimization scenarios.

Sending Media via URL (up to 10MB)

Provide a publicly accessible HTTPS URL with a supported media type in the url field of a media part.

{
  "parts": [
    { "type": "media", "url": "https://your-cdn.com/images/photo.jpg" }
  ]
}

This works with any URL you already host — no pre-upload step required. Maximum file size: 10MB.

Pre-Upload (required for files over 10MB)

Use POST /v3/attachments when you want to:

  • Send files larger than 10MB (up to 100MB) — URL-based downloads are limited to 10MB
  • Send the same file to many recipients — upload once, reuse the attachment_id without re-downloading each time
  • Reduce message send latency — the file is already stored, so sending is faster

How it works:

  1. POST /v3/attachments with file metadata → returns a presigned upload_url (valid for 15 minutes) and a permanent attachment_id
  2. PUT the raw file bytes to the upload_url with the required_headers (no JSON or multipart — just the binary content)
  3. Reference the attachment_id in your media part when sending messages (no expiration)

Key difference: When you provide an external url, we download and process the file on every send. When you use a pre-uploaded attachment_id, the file is already stored — so repeated sends skip the download step entirely.

Domain Allowlisting

Attachment URLs in API responses are served from cdn.linqapp.com. This includes:

  • url fields in media and voice memo message parts
  • download_url fields in attachment and upload response objects

If your application enforces domain allowlists (e.g., for SSRF protection), add:

cdn.linqapp.com

Supported File Types

  • Images: JPEG, PNG, GIF, HEIC, HEIF, TIFF, BMP
  • Videos: MP4, MOV, M4V
  • Audio: M4A, AAC, MP3, WAV, AIFF, CAF, AMR
  • Documents: PDF, TXT, RTF, CSV, Office formats, ZIP
  • Contact & Calendar: VCF, ICS

Audio: Attachment vs Voice Memo

Audio files sent as media parts appear as downloadable file attachments in iMessage. To send audio as an iMessage voice memo bubble (with native inline playback UI), use the dedicated POST /v3/chats/{chatId}/voicememo endpoint instead.

File Size Limits

  • URL-based (url field): 10MB maximum
  • Pre-upload (attachment_id): 100MB maximum
Pre-upload a file
client.attachments.create(AttachmentCreateParams { content_type, filename, size_bytes } body, RequestOptionsoptions?): AttachmentCreateResponse { attachment_id, download_url, expires_at, 3 more }
POST/v3/attachments
Get attachment metadata
client.attachments.retrieve(stringattachmentID, RequestOptionsoptions?): AttachmentRetrieveResponse { id, content_type, created_at, 4 more }
GET/v3/attachments/{attachmentId}
ModelsExpand Collapse
SupportedContentType = "image/jpeg" | "image/png" | "image/gif" | 47 more

Supported MIME types for file attachments and media URLs.

Images: image/jpeg, image/png, image/gif, image/heic, image/heif, image/tiff, image/bmp, image/svg+xml, image/webp, image/x-icon

Videos: video/mp4, video/quicktime, video/mpeg, video/mpeg2, video/x-msvideo, video/3gpp

Audio: audio/mpeg, audio/x-m4a, audio/x-caf, audio/x-wav, audio/x-aiff, audio/aac, audio/midi, audio/amr

Documents: application/pdf, text/plain, text/markdown, text/vcard, text/rtf, text/csv, text/html, text/calendar, text/xml, application/json, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation, application/x-iwork-pages-sffpages, application/x-iwork-numbers-sffnumbers, application/x-iwork-keynote-sffkey, application/epub+zip, application/zip, application/x-gzip

Transcoded on delivery:

  • audio/x-caf — CAF files are transcoded to audio/mp4 for delivery.

Deprecated (accepted but transcoded):

  • audio/mp3 — Deprecated. Use audio/mpeg instead. Files sent as audio/mp3 will be delivered as audio/mpeg.
  • audio/mp4 — Deprecated. Use audio/x-m4a instead. Files sent as audio/mp4 will be delivered as audio/x-m4a.
  • audio/aiff — Deprecated. Use audio/x-aiff instead. Files sent as audio/aiff will be delivered as audio/x-aiff.
  • image/tiff — Accepted, but TIFF images are transcoded to JPEG for delivery.

Unsupported: FLAC, OGG, and executable files are explicitly rejected.

One of the following:
"image/jpeg"
"image/png"
"image/gif"
"image/heic"
"image/heif"
"image/tiff"
"image/bmp"
"image/svg+xml"
"image/webp"
"image/x-icon"
"video/mp4"
"video/quicktime"
"video/mpeg"
"video/mpeg2"
"video/x-m4v"
"video/x-msvideo"
"video/3gpp"
"audio/mpeg"
"audio/mp3"
"audio/x-m4a"
"audio/mp4"
"audio/x-caf"
"audio/x-wav"
"audio/x-aiff"
"audio/aiff"
"audio/aac"
"audio/midi"
"audio/amr"
"application/pdf"
"text/plain"
"text/markdown"
"text/vcard"
"text/rtf"
"text/csv"
"text/html"
"text/calendar"
"application/msword"
"application/vnd.openxmlformats-officedocument.wordprocessingml.document"
"application/vnd.ms-excel"
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
"application/vnd.ms-powerpoint"
"application/vnd.openxmlformats-officedocument.presentationml.presentation"
"application/x-iwork-pages-sffpages"
"application/x-iwork-numbers-sffnumbers"
"application/x-iwork-keynote-sffkey"
"application/epub+zip"
"text/xml"
"application/json"
"application/zip"
"application/x-gzip"
AttachmentCreateResponse { attachment_id, download_url, expires_at, 3 more }
attachment_id: string

Unique identifier for the attachment (for status checks via GET /v3/attachments/{id})

formatuuid
download_url: string

Permanent CDN URL for the file. Does not expire. Use the attachment_id to reference this file in media parts when sending messages.

formaturi
expires_at: string

When the upload URL expires (15 minutes from now)

formatdate-time
http_method: "PUT"

HTTP method to use for upload (always PUT)

required_headers: Record<string, string>

HTTP headers that must be set on the upload request. The presigned URL is signed with these exact values — S3 will reject the upload if they don’t match.

upload_url: string

Presigned URL for uploading the file. PUT the raw binary file content to this URL with the required_headers. Do not JSON-encode or multipart-wrap the body. Expires after 15 minutes.

formaturi
AttachmentRetrieveResponse { id, content_type, created_at, 4 more }
id: string

Unique identifier for the attachment (UUID)

content_type: SupportedContentType

Supported MIME types for file attachments and media URLs.

Images: image/jpeg, image/png, image/gif, image/heic, image/heif, image/tiff, image/bmp, image/svg+xml, image/webp, image/x-icon

Videos: video/mp4, video/quicktime, video/mpeg, video/mpeg2, video/x-msvideo, video/3gpp

Audio: audio/mpeg, audio/x-m4a, audio/x-caf, audio/x-wav, audio/x-aiff, audio/aac, audio/midi, audio/amr

Documents: application/pdf, text/plain, text/markdown, text/vcard, text/rtf, text/csv, text/html, text/calendar, text/xml, application/json, application/msword, application/vnd.openxmlformats-officedocument.wordprocessingml.document, application/vnd.ms-excel, application/vnd.openxmlformats-officedocument.spreadsheetml.sheet, application/vnd.ms-powerpoint, application/vnd.openxmlformats-officedocument.presentationml.presentation, application/x-iwork-pages-sffpages, application/x-iwork-numbers-sffnumbers, application/x-iwork-keynote-sffkey, application/epub+zip, application/zip, application/x-gzip

Transcoded on delivery:

  • audio/x-caf — CAF files are transcoded to audio/mp4 for delivery.

Deprecated (accepted but transcoded):

  • audio/mp3 — Deprecated. Use audio/mpeg instead. Files sent as audio/mp3 will be delivered as audio/mpeg.
  • audio/mp4 — Deprecated. Use audio/x-m4a instead. Files sent as audio/mp4 will be delivered as audio/x-m4a.
  • audio/aiff — Deprecated. Use audio/x-aiff instead. Files sent as audio/aiff will be delivered as audio/x-aiff.
  • image/tiff — Accepted, but TIFF images are transcoded to JPEG for delivery.

Unsupported: FLAC, OGG, and executable files are explicitly rejected.

One of the following:
"image/jpeg"
"image/png"
"image/gif"
"image/heic"
"image/heif"
"image/tiff"
"image/bmp"
"image/svg+xml"
"image/webp"
"image/x-icon"
"video/mp4"
"video/quicktime"
"video/mpeg"
"video/mpeg2"
"video/x-m4v"
"video/x-msvideo"
"video/3gpp"
"audio/mpeg"
"audio/mp3"
"audio/x-m4a"
"audio/mp4"
"audio/x-caf"
"audio/x-wav"
"audio/x-aiff"
"audio/aiff"
"audio/aac"
"audio/midi"
"audio/amr"
"application/pdf"
"text/plain"
"text/markdown"
"text/vcard"
"text/rtf"
"text/csv"
"text/html"
"text/calendar"
"application/msword"
"application/vnd.openxmlformats-officedocument.wordprocessingml.document"
"application/vnd.ms-excel"
"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
"application/vnd.ms-powerpoint"
"application/vnd.openxmlformats-officedocument.presentationml.presentation"
"application/x-iwork-pages-sffpages"
"application/x-iwork-numbers-sffnumbers"
"application/x-iwork-keynote-sffkey"
"application/epub+zip"
"text/xml"
"application/json"
"application/zip"
"application/x-gzip"
created_at: string

When the attachment was created

formatdate-time
filename: string

Original filename of the attachment

size_bytes: number

Size of the attachment in bytes

formatint64
status: "pending" | "complete" | "failed"

Current upload/processing status

One of the following:
"pending"
"complete"
"failed"
download_url?: string

URL to download the attachment

formaturi
© 2026 Linq, Inc. · linqapp.com