Attachments

Files on inbound mail arrive as metadata — filename, content type, size — never as inline bytes. When you need the file, mint a short-lived signed link you can hand to a browser or another service, or download the bytes directly. Every attachment read uses the messages:read scope.

Read attachment metadata

Attachment ids come from the attachments array on a fetched message. Fetch one to get its filename, content type, size, and the message it belongs to.

curl https://api.dairo.app/v1/attachments/f3b1d2a4-6c78-49e0-8b5f-0a1c2d3e4f56 \
  -H "Authorization: Bearer $DAIRO_API_KEY"

{
  "object": "attachment",
  "id": "f3b1d2a4-6c78-49e0-8b5f-0a1c2d3e4f56",
  "messageId": "8a2fdc3b-51e2-4f6a-9c11-2b7e4d9a6f3c",
  "filename": "damage-photo.jpg",
  "contentType": "image/jpeg",
  "sizeBytes": 182034,
  "contentId": null,
  "disposition": "attachment",
  "createdAt": "2026-07-10T14:32:08+00:00"
}

The disposition is attachment for a normal file or inline for one referenced from the HTML body (an embedded image, say).

Get the file

Three endpoints serve the file, each for a different consumer:

On /url and /link, expiryHours sets how long the links stay valid — an integer from 1 to 168 (one week). Omit it and the links last five minutes.

curl "https://api.dairo.app/v1/attachments/f3b1d2a4-6c78-49e0-8b5f-0a1c2d3e4f56/url?expiryHours=1" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

# Or fetch the bytes straight to disk
curl -o damage-photo.jpg \
  https://api.dairo.app/v1/attachments/f3b1d2a4-6c78-49e0-8b5f-0a1c2d3e4f56/download \
  -H "Authorization: Bearer $DAIRO_API_KEY"

{
  "attachment": {
    "id": "f3b1d2a4-6c78-49e0-8b5f-0a1c2d3e4f56",
    "messageId": "8a2fdc3b-51e2-4f6a-9c11-2b7e4d9a6f3c",
    "filename": "damage-photo.jpg",
    "contentType": "image/jpeg",
    "sizeBytes": 182034
  },
  "downloadUrl": "https://storage.dairo.app/d/dl.MC4xNGE2…/damage-photo.jpg",
  "shareUrl": "https://storage.dairo.app/s/dl.MC4xNGE2…",
  "expiresInSeconds": 3600
}

Dairo scans inbound files for malware. Until a file passes, downloadUrl is a short-lived direct link for you alone and shareUrl is null; GET /v1/attachments/{id}/link, which only returns branded links, answers 409 until then. Once the scan passes you get the branded links shown above. A file the scan flags is withheld — requests for it return 403.

Share a file by link

The shareUrl is a human-friendly download page — handy when you want to hand a file to someone in an email. Dairo never inserts links into your mail for you: mint the link, then place it in your text or html deliberately.

Two things to keep in mind when sharing inbound files onward:

• A share link exists only for an inbound file that passed Dairo's malware scan; until then there is no shareUrl to hand out.
• Sharing a file onward means vouching for a file you didn't author. The page is hosted by Dairo, but the file behind it is whatever the sender attached — confirm it's safe before distributing the link.

Next steps

• Send an email — attach files to outbound mail.
• Share links — the same short-lived links over files in your own storage buckets.
• API reference — every endpoint, with copy-paste requests.