Core concepts

Attachments

Send files with a message and download the files that arrive.

Sending attachments

send and reply accept an attachments array. Each entry has a filename, a contentType, and the file's bytes as base64 content.

curl "https://api.goshenemail.com/v1/inboxes/research%40agents.goshenemail.com/messages/send" \
  -H "Authorization: Bearer $GOSHENEMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
{
  "to": ["vendor@example.net"],
  "subject": "Purchase order 0419",
  "text": "The signed purchase order is attached.",
  "attachments": [
    { "filename": "po-0419.pdf", "contentType": "application/pdf", "content": "JVBERi0xLjQK..." }
  ],
  "idempotencyKey": "6a1f7d2c-0b3e-4f7a-9c1d-2e8b5a4c3d10"
}
EOF

Limits per message: up to 10 files, 2 MiB combined after base64 decoding, filenames of 1 to 200 characters, and a contentType in type/subtype form. Bodies (text plus html) are limited separately to 512 KiB. See Limits.

Receiving attachments

Messages list their attachments with an id, name, type, and size:

"attachments": [
  { "attachmentId": "4f40dbb7-c2aa-4288-af1e-2966ca55b6b7", "filename": "quote.pdf", "contentType": "application/pdf", "size": 48213 }
]

The bytes are not inlined. Ask for a download URL:

curl "https://api.goshenemail.com/v1/inboxes/research%40agents.goshenemail.com/messages/%3Cid%40example.net%3E/attachments/4f40dbb7-c2aa-4288-af1e-2966ca55b6b7" \
  -H "Authorization: Bearer $GOSHENEMAIL_API_KEY"

{
  "downloadUrl": "https://api.goshenemail.com/attachments/...?expires=1758400000&signature=...",
  "attachmentId": "4f40dbb7-c2aa-4288-af1e-2966ca55b6b7",
  "expiresAt": "2026-09-20T18:10:12.000Z",
  "filename": "quote.pdf",
  "contentType": "application/pdf",
  "size": 48213
}

The URL is signed and valid for five minutes. Fetch it without an Authorization header. Request a new URL if it expires; the attachment stays with the message.

Threads report attachmentCount, and getThread includes each message's attachment list, so an agent can find files across a conversation without reading every message.

Scanning

Incoming attachments are scanned for malware along with the rest of the message. A message with a flagged attachment goes to quarantine, and it cannot be released while the antivirus result is anything other than clean. Attachment content is untrusted data even when it passes the scan: a PDF or spreadsheet can carry text that reads like instructions. See Building agents on email.