Skip to main content
POST
/
api
/
v1
/
attachments
/
presigned-url
Create Attachment Upload
curl --request POST \
  --url https://api.example.com/api/v1/attachments/presigned-url \
  --header 'Content-Type: application/json' \
  --data '
{
  "filename": "<string>",
  "contentType": "<string>",
  "size": 123,
  "inline": true
}
'
{
  "attachmentId": "<string>",
  "uploadUrl": "<string>",
  "expiresAt": "<string>",
  "contentId": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.mailbreeze.com/llms.txt

Use this file to discover all available pages before exploring further.

Create a presigned URL for uploading an email attachment. After uploading the file to this URL, you must confirm the upload before using the attachment.

Upload Flow

Attachments use a three-step process:
  1. Create Upload - Get a presigned URL (this endpoint)
  2. Upload File - PUT the file directly to the presigned URL
  3. Confirm Upload - Notify MailBreeze the upload is complete
  4. Use Attachment - Include attachment ID when sending emails

Request Body

filename
string
required
Original filename (e.g., report.pdf). Used for display in email clients.
contentType
string
required
MIME type of the file (e.g., application/pdf, image/png).
size
integer
required
File size in bytes. Maximum 40MB for regular attachments, 5MB for inline images.
inline
boolean
default:"false"
Set to true for embedded images in HTML emails (returns contentId).

Examples

import { MailBreeze } from "mailbreeze";

const mailbreeze = new MailBreeze({ apiKey: "sk_live_xxx" });

// Step 1: Create upload URL
const { attachmentId, uploadUrl, uploadToken, expiresAt } =
  await mailbreeze.attachments.createUpload({
    fileName: "report.pdf",
    contentType: "application/pdf",
    fileSize: 1024000, // ~1MB
  });

console.log(`Upload URL expires at: ${expiresAt}`);

// Step 2: Upload file directly to the presigned URL
const fileBuffer = await fs.readFile("./report.pdf");
await fetch(uploadUrl, {
  method: "PUT",
  body: fileBuffer,
  headers: {
    "Content-Type": "application/pdf",
    "Content-Length": fileBuffer.length.toString(),
  },
});

// Step 3: Confirm the upload
const attachment = await mailbreeze.attachments.confirm({ uploadToken });
console.log(attachment.status); // "uploaded"

// Step 4: Use in email
await mailbreeze.emails.send({
  from: "hello@yourdomain.com",
  to: "user@example.com",
  subject: "Your report is ready",
  html: "<p>Please find your report attached.</p>",
  attachmentIds: [attachmentId],
});

Response

attachmentId
string
Unique attachment ID to use when sending emails.
uploadUrl
string
Presigned URL for uploading the file. PUT your file here.
expiresAt
string
ISO 8601 timestamp when the upload URL expires (typically 1 hour).
contentId
string
For inline attachments only. Use this in HTML: <img src="cid:contentId">.
Example Response
{
  "success": true,
  "data": {
    "attachmentId": "att_abc123",
    "uploadUrl": "https://storage.mailbreeze.com/uploads/att_abc123?signature=...",
    "expiresAt": "2024-01-15T11:30:00Z"
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00.000Z",
    "requestId": "req_abc123",
    "path": "/api/v1/attachments/presigned-url"
  }
}
Example Response (Inline Image)
{
  "success": true,
  "data": {
    "attachmentId": "att_abc123",
    "uploadUrl": "https://storage.mailbreeze.com/uploads/att_abc123?signature=...",
    "expiresAt": "2024-01-15T11:30:00Z",
    "contentId": "image001"
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00.000Z",
    "requestId": "req_abc123",
    "path": "/api/v1/attachments/presigned-url"
  }
}

Limits

LimitValue
Max file size10MB
Upload URL validity1 hour
Attachment validity7 days after confirmation
Max attachments per email10
Max total attachment size per email25MB

Errors

CodeHTTP StatusDescription
ATTACHMENT_TOO_LARGE400File size exceeds 10MB limit
INVALID_CONTENT_TYPE400Unsupported MIME type
VALIDATION_ERROR400Missing or invalid parameters