Pièces jointes

attachments est un tableau de 50 objets au maximum. Chaque pièce jointe requiert un filename et exactement un des champs content ou path.

filenamestringrequis

De 1 à 255 caractères. Affiché au destinataire.

contentstringfacultatif

Octets du fichier en base64. Le SDK accepte aussi un Buffer/Uint8Array et l'encode pour vous. Utilisez ce champ ou path.

pathstringfacultatif

Une URL https publique. SpacePost la télécharge lors de l'envoi de l'e-mail. Utilisez ce champ ou content.

content_typestringfacultatif

Type MIME, comme application/pdf. Alias contentType dans le SDK.

content_idstringfacultatif

Rend la pièce jointe « en ligne » : elle est référençable sous la forme cid:<content_id> dans votre HTML. Alias contentId dans le SDK.

Limites

• Le message entier, y compris toutes les pièces jointes après encodage base64, doit peser moins de 40 Mo. Le base64 gonfle les fichiers d’environ 33 %, gardez donc le total brut sous 30 Mo environ.
• Les pièces jointes par URL (path) doivent utiliser https, doivent résoudre vers une adresse publique (les réseaux privés sont refusés), sont récupérées avec un délai d’attente de 10 secondes et ne doivent pas rediriger. Un échec de récupération marque l’e-mail comme failed.
• Le contenu des pièces jointes est supprimé du stockage une fois l’e-mail envoyé ; seules les métadonnées (nom, type, taille) sont conservées dans le journal.

Joindre un fichier par son contenu

Node.js

attachment.ts

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

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)\"
    }]
  }"

Sur macOS, utilisez base64 -i invoice-1042.pdf (sans -w0).

Python

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}],
    },
)

Joindre un fichier par 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" }]
}

Attention

Fournir à la fois content et path, ou aucun des deux, renvoie 422 : « Each attachment needs exactly one of content or path ».

Images en ligne

Définissez un content_id et référencez-le avec une URL cid: dans votre HTML.

inline-image.ts

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" }],
});

Les images en ligne sont envoyées avec le message et s’affichent sans requête réseau, mais de nombreux clients (Gmail sur le web en particulier) les affichent mieux lorsqu’elles sont petites. Pour les grandes images, hébergez-les sur votre propre CDN et utilisez une URL https:// classique.