v1.3.0: add attachment download support

Add getAttachment to remote provider — calls /v1/attachment (hosted)
or /api/attachment (self-hosted) to download binary attachments.
CLI inbox detail now shows attachment IDs and supports --save flag
to download all attachments to disk. Inbox list shows +Natt indicator
for emails with attachments.

New e2e tests hit live APIs: OSS worker (test.mails.dev) for attachment
metadata, hosted worker (mails.dev) for binary download via R2.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: guo-yu

package.json

@@ -1,6 +1,6 @@
 {
   "name": "mails",
-  "version": "1.2.4",
+  "version": "1.3.0",
   "description": "Email infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",

src/cli/commands/help.ts

@@ -32,6 +32,8 @@ Inbox:
   mails inbox --query "reset password"  Search emails in a mailbox
   mails inbox --query "invoice" --direction inbound --limit 10
   mails inbox <id>                      Show email details
+  mails inbox <id> --save               Download attachments to current directory
+  mails inbox <id> --save ./downloads   Download attachments to a directory
 
 Code:
   mails code --to <address>             Wait for a verification code

src/cli/commands/inbox.ts

@@ -1,4 +1,6 @@
-import { getInbox, searchInbox, getEmail } from '../../core/receive.js'
+import { writeFile, mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { getInbox, searchInbox, getEmail, downloadAttachment } from '../../core/receive.js'
 import { loadConfig } from '../../core/config.js'
 
 function parseArgs(args: string[]): Record<string, string> {
@@ -11,6 +13,8 @@ function parseArgs(args: string[]): Record<string, string> {
       if (value && !value.startsWith('--')) {
         result[key] = value
         i++
+      } else {
+        result[key] = ''
       }
     } else if (!result._positional) {
       result._positional = arg
@@ -38,12 +42,32 @@ export async function inboxCommand(args: string[]) {
     if (email.attachments?.length) {
       console.log('Attachments:')
       for (const attachment of email.attachments) {
-        const size = attachment.size_bytes ?? 0
-        console.log(`- ${attachment.filename} (${attachment.content_type}, ${size} bytes)`)
+        const size = attachment.size_bytes ?? (attachment as unknown as Record<string, unknown>).size ?? 0
+        console.log(`  ${attachment.id}  ${attachment.filename} (${attachment.content_type}, ${size} bytes)`)
       }
     }
     console.log('---')
     console.log(email.body_text || '(no text body)')
+
+    // --save: download all attachments to disk
+    if (opts.save !== undefined && email.attachments?.length) {
+      const dir = opts.save || '.'
+      await mkdir(dir, { recursive: true })
+      for (const att of email.attachments) {
+        try {
+          const download = await downloadAttachment(att.id)
+          if (!download) {
+            console.error(`Attachment not found: ${att.id}`)
+            continue
+          }
+          const dest = join(dir, download.filename)
+          await writeFile(dest, Buffer.from(download.data))
+          console.log(`Saved: ${dest}`)
+        } catch (err) {
+          console.error(`Failed to download ${att.filename}: ${(err as Error).message}`)
+        }
+      }
+    }
     return
   }
 
@@ -72,7 +96,8 @@ export async function inboxCommand(args: string[]) {
 
   for (const email of emails) {
     const code = email.code ? ` [${email.code}]` : ''
+    const clip = email.attachment_count ? ` +${email.attachment_count}att` : ''
     const from = email.from_name || email.from_address
-    console.log(`${email.id.slice(0, 8)}  ${email.received_at.slice(0, 16)}  ${from.padEnd(24).slice(0, 24)}  ${email.subject.slice(0, 40)}${code}`)
+    console.log(`${email.id.slice(0, 8)}  ${email.received_at.slice(0, 16)}  ${from.padEnd(24).slice(0, 24)}  ${email.subject.slice(0, 40)}${code}${clip}`)
   }
 }

src/cli/index.ts

@@ -35,7 +35,7 @@ async function main() {
     case 'version':
     case '--version':
     case '-v':
-      console.log('mails v1.2.4')
+      console.log('mails v1.3.0')
       break
     default:
       console.error(`Unknown command: ${command}`)

src/core/receive.ts

@@ -1,4 +1,4 @@
-import type { Email, EmailQueryOptions, EmailSearchOptions } from './types.js'
+import type { AttachmentDownload, Email, EmailQueryOptions, EmailSearchOptions } from './types.js'
 import { getStorage } from './storage.js'
 
 export async function getInbox(mailbox: string, options?: EmailQueryOptions): Promise<Email[]> {
@@ -19,6 +19,14 @@ export async function getEmail(id: string): Promise<Email | null> {
   return storage.getEmail(id)
 }
 
+export async function downloadAttachment(id: string): Promise<AttachmentDownload | null> {
+  const storage = await getStorage()
+  if (!storage.getAttachment) {
+    throw new Error(`Storage provider "${storage.name}" does not support attachment downloads`)
+  }
+  return storage.getAttachment(id)
+}
+
 export async function waitForCode(mailbox: string, options?: {
   timeout?: number
   since?: string

src/core/types.ts

@@ -118,6 +118,12 @@ export interface EmailSearchOptions extends EmailQueryOptions {
   query: string
 }
 
+export interface AttachmentDownload {
+  data: ArrayBuffer
+  filename: string
+  contentType: string
+}
+
 export interface StorageProvider {
   name: string
   init(): Promise<void>
@@ -129,4 +135,5 @@ export interface StorageProvider {
     timeout?: number
     since?: string
   }): Promise<{ code: string; from: string; subject: string } | null>
+  getAttachment?(id: string): Promise<AttachmentDownload | null>
 }

src/index.ts

@@ -1,5 +1,5 @@
 export { send } from './core/send.js'
-export { getInbox, searchInbox, getEmail, waitForCode } from './core/receive.js'
+export { getInbox, searchInbox, getEmail, waitForCode, downloadAttachment } from './core/receive.js'
 export { getStorage } from './core/storage.js'
 export { loadConfig, saveConfig, getConfigValue, setConfigValue } from './core/config.js'
 export { createResendProvider } from './providers/send/resend.js'
@@ -10,6 +10,7 @@ export { createRemoteProvider } from './providers/storage/remote.js'
 
 export type {
   Attachment,
+  AttachmentDownload,
   AttachmentTextExtractionStatus,
   Email,
   PreparedAttachment,

src/providers/storage/remote.ts

@@ -1,4 +1,4 @@
-import type { Email, EmailQueryOptions, EmailSearchOptions, StorageProvider } from '../../core/types.js'
+import type { AttachmentDownload, Email, EmailQueryOptions, EmailSearchOptions, StorageProvider } from '../../core/types.js'
 
 interface RemoteProviderOptions {
   /** Worker API base URL */
@@ -34,6 +34,7 @@ export function createRemoteProvider(options: RemoteProviderOptions): StoragePro
   function inboxPath() { return useAuthApi ? '/v1/inbox' : '/api/inbox' }
   function codePath() { return useAuthApi ? '/v1/code' : '/api/code' }
   function emailPath() { return useAuthApi ? '/v1/email' : '/api/email' }
+  function attachmentPath() { return useAuthApi ? '/v1/attachment' : '/api/attachment' }
 
   function withMailbox(params: Record<string, string | number>): Record<string, string | number> {
     if (!useAuthApi) {
@@ -90,6 +91,22 @@ export function createRemoteProvider(options: RemoteProviderOptions): StoragePro
       return await res.json() as Email
     },
 
+    async getAttachment(id): Promise<AttachmentDownload | null> {
+      const res = await apiFetch(attachmentPath(), { id })
+      if (!res.ok) {
+        if (res.status === 404) return null
+        const data = await res.json() as { error?: string }
+        throw new Error(`API error: ${data.error ?? res.statusText}`)
+      }
+      const contentDisposition = res.headers.get('Content-Disposition') ?? ''
+      const filenameMatch = contentDisposition.match(/filename="([^"]+)"/)
+      return {
+        data: await res.arrayBuffer(),
+        filename: filenameMatch?.[1] ?? 'download',
+        contentType: res.headers.get('Content-Type') ?? 'application/octet-stream',
+      }
+    },
+
     async getCode(_mailbox, options) {
       const res = await apiFetch(codePath(), withMailbox({
         timeout: options?.timeout ?? 30,