Attachment Handling

Manage email attachments through dedicated endpoints. Upload files to be referenced in emails, retrieve attachment metadata, and delete unused attachments.

Upload Attachment

Upload a file to be used as an email attachment.

Endpoint

POST /api/email/attachments

Authentication

Required: Bearer token in Authorization header

Authorization: Bearer YOUR_API_KEY

Content-Type

Content-Type: multipart/form-data

Request Body

Field	Type	Required	Description
`file`	File	Yes	The file to upload
`filename`	string	No	Custom filename (defaults to original)

Request Example

curl -X POST https://api.yourdomain.com/api/email/attachments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "filename=invoice-jan-2024.pdf"

Response (201 Created)

{
  "success": true,
  "data": {
    "id": "att_1234567890",
    "filename": "invoice-jan-2024.pdf",
    "contentType": "application/pdf",
    "size": 245760,
    "url": "https://api.yourdomain.com/api/email/attachments/att_1234567890",
    "downloadUrl": "https://cdn.yourdomain.com/attachments/att_1234567890.pdf",
    "createdAt": "2024-01-20T10:00:00Z",
    "expiresAt": "2024-02-20T10:00:00Z"
  },
  "message": "Attachment uploaded successfully"
}

List Attachments

Retrieve all attachments for your account.

Endpoint

GET /api/email/attachments

Authentication

Required: Bearer token in Authorization header

Query Parameters

Parameter	Type	Description
`limit`	number	Number of results per page (default: 20, max: 100)
`offset`	number	Pagination offset
`search`	string	Search by filename

Response (200 OK)

{
  "success": true,
  "data": {
    "attachments": [
      {
        "id": "att_1234567890",
        "filename": "document.pdf",
        "contentType": "application/pdf",
        "size": 245760,
        "createdAt": "2024-01-20T10:00:00Z",
        "expiresAt": "2024-02-20T10:00:00Z"
      },
      {
        "id": "att_0987654321",
        "filename": "image.png",
        "contentType": "image/png",
        "size": 1048576,
        "createdAt": "2024-01-19T15:30:00Z",
        "expiresAt": "2024-02-19T15:30:00Z"
      }
    ],
    "pagination": {
      "total": 45,
      "limit": 20,
      "offset": 0,
      "hasMore": true
    }
  },
  "message": "Attachments retrieved successfully"
}

Get Attachment

Retrieve metadata for a specific attachment.

Endpoint

GET /api/email/attachments/:id

Authentication

Required: Bearer token in Authorization header

Path Parameters

Parameter	Description
`id`	The attachment ID (e.g., `att_1234567890`)

Response (200 OK)

{
  "success": true,
  "data": {
    "id": "att_1234567890",
    "filename": "document.pdf",
    "contentType": "application/pdf",
    "size": 245760,
    "url": "https://api.yourdomain.com/api/email/attachments/att_1234567890",
    "downloadUrl": "https://cdn.yourdomain.com/attachments/att_1234567890.pdf",
    "createdAt": "2024-01-20T10:00:00Z",
    "expiresAt": "2024-02-20T10:00:00Z",
    "usedIn": [
      {
        "messageId": "msg_abc123xyz",
        "sentAt": "2024-01-20T10:05:00Z"
      }
    ]
  },
  "message": "Attachment retrieved successfully"
}

Download Attachment

Download the actual file content of an attachment.

Endpoint

GET /api/email/attachments/:id/download

Authentication

Required: Bearer token in Authorization header

Response

Returns the file with appropriate Content-Type and Content-Disposition headers.

Content-Type: application/pdf
Content-Disposition: attachment; filename="document.pdf"
Content-Length: 245760

Request Example

curl -O -J \
  -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.yourdomain.com/api/email/attachments/att_1234567890/download

Delete Attachment

Permanently delete an attachment.

Endpoint

DELETE /api/email/attachments/:id

Authentication

Required: Bearer token in Authorization header

Request Example

curl -X DELETE https://api.yourdomain.com/api/email/attachments/att_1234567890 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response (200 OK)

{
  "success": true,
  "data": {
    "id": "att_1234567890",
    "deletedAt": "2024-01-20T15:30:00Z"
  },
  "message": "Attachment deleted successfully"
}

Using Attachments in Emails

Reference uploaded attachments when sending emails:

Method 1: Attachment ID

{
  "from": "sender@example.com",
  "to": "recipient@example.com",
  "subject": "Document Attached",
  "text": "Please find the document attached.",
  "attachments": [
    {
      "id": "att_1234567890"
    }
  ]
}

Method 2: Inline Base64

{
  "from": "sender@example.com",
  "to": "recipient@example.com",
  "subject": "Document Attached",
  "text": "Please find the document attached.",
  "attachments": [
    {
      "filename": "document.pdf",
      "content": "base64encodedcontent...",
      "contentType": "application/pdf"
    }
  ]
}

Supported File Types

Category	MIME Types
Documents	`application/pdf`, `application/msword`, `application/vnd.openxmlformats-officedocument.wordprocessingml.document`, `text/plain`
Images	`image/jpeg`, `image/png`, `image/gif`, `image/webp`
Spreadsheets	`application/vnd.ms-excel`, `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`, `text/csv`
Archives	`application/zip`, `application/gzip`

Limits

Limit	Value
Max file size	25 MB per file
Max total email size	25 MB (including all attachments)
Storage retention	30 days for unused attachments
Max attachments per email	50

Error Responses

413 Payload Too Large

{
  "success": false,
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File size exceeds 25MB limit",
    "maxSize": 26214400,
    "actualSize": 52428800
  }
}

415 Unsupported Media Type

{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_FILE_TYPE",
    "message": "File type not allowed",
    "contentType": "application/x-executable"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "ATTACHMENT_NOT_FOUND",
    "message": "Attachment not found or expired"
  }
}

Best Practices

Upload before sending - Upload attachments first, then reference by ID in send requests
Compress large files - Use ZIP for multiple files or large documents
Use appropriate formats - PDF for documents, optimized images for photos
Clean up unused attachments - Delete attachments that are no longer needed
Check file sizes - Validate file size client-side before upload
Handle expiration - Attachments expire after 30 days if not used in an email

Code Examples

JavaScript - Upload and Send

// Upload attachment
const formData = new FormData();
formData.append('file', fileInput.files[0]);

const uploadRes = await fetch('/api/email/attachments', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  body: formData
});
const { data: attachment } = await uploadRes.json();

// Send email with attachment
await fetch('/api/email/send', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: 'sender@example.com',
    to: 'recipient@example.com',
    subject: 'Document',
    attachments: [{ id: attachment.id }]
  })
});

Attachment Handling

On this page