첨부 파일

attachments는 최대 50개의 객체로 이루어진 배열입니다. 각 첨부 파일에는 filename이 필요하고, content와 path 중 정확히 하나를 지정해야 합니다.

filenamestring필수

1자 이상 255자 이하. 수신자에게 표시됩니다.

contentstring선택

base64로 인코딩한 파일 바이트. SDK는 Buffer/Uint8Array도 받아서 대신 인코딩해 줍니다. 이 필드나 path 중 하나를 사용하세요.

pathstring선택

공개 https URL. 이메일을 보낼 때 SpacePost가 다운로드합니다. 이 필드나 content 중 하나를 사용하세요.

content_typestring선택

application/pdf 같은 MIME 유형. SDK에서는 contentType 별칭을 사용합니다.

content_idstring선택

첨부 파일을 인라인으로 만들며, HTML에서 cid:<content_id>로 참조할 수 있습니다. SDK에서는 contentId 별칭을 사용합니다.

한도

base64 인코딩 후 모든 첨부 파일을 포함한 메시지 전체가 40 MB 미만이어야 합니다. base64는 파일 크기를 약 33% 늘리므로 원본 합계는 대략 30 MB 이하로 유지하세요.
URL 첨부 파일(path)은 https를 사용해야 하고, 공개 주소로 해석되어야 하며(사설 네트워크는 거부됩니다), 10초 제한 시간으로 가져오고, 리디렉션되면 안 됩니다. 가져오기에 실패하면 이메일이 failed로 표시됩니다.
첨부 파일 바이트는 이메일이 발송되면 저장소에서 삭제되며, 로그에는 메타데이터(이름, 유형, 크기)만 남습니다.

내용으로 파일 첨부하기

import { readFile } from "node:fs/promises";
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

const { data, error } = await spacepost.emails.send({
  from: "Acme <billing@acme.com>",
  to: "user@example.com",
  subject: "Invoice 1042",
  text: "Your invoice is attached.",
  attachments: [{ filename: "invoice-1042.pdf", content: await readFile("invoice-1042.pdf"), contentType: "application/pdf" }],
});

console.log(error ?? data);

curl -X POST https://api.spacepost.dev/emails \
  -H "Authorization: Bearer $SPACEPOST_API_KEY" -H "Content-Type: application/json" \
  -d "{
    \"from\": \"Acme <billing@acme.com>\",
    \"to\": [\"user@example.com\"],
    \"subject\": \"Invoice 1042\",
    \"text\": \"Your invoice is attached.\",
    \"attachments\": [{
      \"filename\": \"invoice-1042.pdf\",
      \"content_type\": \"application/pdf\",
      \"content\": \"$(base64 -w0 invoice-1042.pdf)\"
    }]
  }"

macOS에서는 base64 -i invoice-1042.pdf를 사용하세요(-w0 없음).

import base64

with open("invoice-1042.pdf", "rb") as f:
    content = base64.b64encode(f.read()).decode()

requests.post(
    "https://api.spacepost.dev/emails",
    headers={"Authorization": f"Bearer {os.environ['SPACEPOST_API_KEY']}"},
    json={
        "from": "Acme <billing@acme.com>",
        "to": ["user@example.com"],
        "subject": "Invoice 1042",
        "text": "Your invoice is attached.",
        "attachments": [{"filename": "invoice-1042.pdf", "content_type": "application/pdf", "content": content}],
    },
)

URL로 파일 첨부하기

{
  "from": "Acme <billing@acme.com>",
  "to": ["user@example.com"],
  "subject": "Your report",
  "text": "Report attached.",
  "attachments": [{ "filename": "report.pdf", "path": "https://files.acme.com/reports/2026-10.pdf" }]
}

인라인 이미지

content_id를 설정하고 HTML에서 cid: URL로 참조합니다.

import { readFile } from "node:fs/promises";
import { SpacePost } from "@spacepost/node";

const spacepost = new SpacePost(process.env.SPACEPOST_API_KEY);

await spacepost.emails.send({
  from: "Acme <hello@acme.com>",
  to: "user@example.com",
  subject: "Welcome",
  html: '<img src="cid:logo" alt="Acme" width="120" /><p>Welcome aboard.</p>',
  attachments: [{ filename: "logo.png", content: await readFile("logo.png"), contentType: "image/png", contentId: "logo" }],
});

인라인 이미지는 메시지에 포함되어 전송되므로 네트워크 요청 없이 표시되지만, 많은 클라이언트(특히 웹 Gmail)에서는 크기가 작을 때 가장 잘 표시됩니다. 큰 이미지는 직접 운영하는 CDN에 호스팅하고 일반 https:// URL을 사용하세요.