Pièces jointes

Cette page explique comment joindre des fichiers aux e-mails que vous envoyez avec POST /emails, soit en contenu encodé en base64, soit en laissant Emailit les télécharger depuis une URL. Elle traite aussi des images intégrées, des types de fichiers autorisés et des limites de taille.

Champs des pièces jointes

Transmettez un tableau attachments. Chaque élément est un objet avec ces champs :

Joindre un fichier en base64

Lisez le fichier, encodez-le en base64 et envoyez-le avec son type MIME.

curl https://api.emailit.com/v2/emails \
  -H "Authorization: Bearer $EMAILIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"from\": \"Acme Billing <billing@acme.com>\",
    \"to\": \"ada@example.com\",
    \"subject\": \"Invoice INV-1042\",
    \"text\": \"Your invoice is attached.\",
    \"attachments\": [{
      \"filename\": \"INV-1042.pdf\",
      \"content\": \"$(base64 < INV-1042.pdf | tr -d '\n')\",
      \"content_type\": \"application/pdf\"
    }]
  }"

import { readFile } from 'node:fs/promises';
import { Emailit } from '@emailit/node';

const emailit = new Emailit(process.env.EMAILIT_API_KEY);
const pdf = await readFile('INV-1042.pdf');

await emailit.emails.send({
  from: 'Acme Billing <billing@acme.com>',
  to: 'ada@example.com',
  subject: 'Invoice INV-1042',
  text: 'Your invoice is attached.',
  attachments: [
    {
      filename: 'INV-1042.pdf',
      content: pdf.toString('base64'),
      content_type: 'application/pdf',
    },
  ],
});

import base64
import os
from emailit import EmailitClient

client = EmailitClient(os.environ["EMAILIT_API_KEY"])

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

client.emails.send({
    "from": "Acme Billing <billing@acme.com>",
    "to": "ada@example.com",
    "subject": "Invoice INV-1042",
    "text": "Your invoice is attached.",
    "attachments": [{
        "filename": "INV-1042.pdf",
        "content": pdf,
        "content_type": "application/pdf",
    }],
})

$emailit = Emailit::client(getenv('EMAILIT_API_KEY'));

$emailit->emails()->send([
    'from' => 'Acme Billing <billing@acme.com>',
    'to' => 'ada@example.com',
    'subject' => 'Invoice INV-1042',
    'text' => 'Your invoice is attached.',
    'attachments' => [[
        'filename' => 'INV-1042.pdf',
        'content' => base64_encode(file_get_contents('INV-1042.pdf')),
        'content_type' => 'application/pdf',
    ]],
]);

Joindre un fichier depuis une URL

Au lieu d’encoder le fichier vous-même, fournissez une url à Emailit. Emailit télécharge le fichier pendant qu’il construit le message : la requête dure donc aussi longtemps que le téléchargement.

{
  "from": "Acme Billing <billing@acme.com>",
  "to": "ada@example.com",
  "subject": "Invoice INV-1042",
  "text": "Your invoice is attached.",
  "attachments": [
    {
      "filename": "INV-1042.pdf",
      "url": "https://files.acme.com/invoices/INV-1042.pdf"
    }
  ]
}

L’URL doit respecter ces règles, sinon la requête échoue avec 422 et Attachment error :

• Elle utilise http ou https et pointe vers un hôte public. Les adresses privées et internes sont refusées.
• Elle renvoie directement le fichier avec un statut 2xx. Les redirections ne sont pas suivies.
• Le téléchargement se termine en 30 secondes au maximum.
• Le fichier ne dépasse pas 25 Mo, d’après son en-tête Content-Length.

Emailit construit une copie distincte du message pour chaque destinataire et télécharge les pièces jointes par URL pour chaque copie. Assurez-vous que les URL signées ou à durée limitée restent valides pendant toute la requête, et que l’hébergeur du fichier peut supporter un téléchargement par destinataire.

Intégrer des images

Pour afficher une image dans le corps HTML plutôt que comme pièce jointe séparée, donnez-lui un content_id et faites référence à cet ID avec cid: dans une balise img.

{
  "from": "Acme <hello@acme.com>",
  "to": "ada@example.com",
  "subject": "Your weekly report",
  "html": "<p><img src=\"cid:chart-week-40\" alt=\"Weekly signups\" width=\"600\"></p>",
  "attachments": [
    {
      "filename": "chart.png",
      "content": "iVBORw0KGgoAAAANSUhEUgAA...",
      "content_type": "image/png",
      "content_id": "chart-week-40"
    }
  ]
}

Le content_id de la pièce jointe et la valeur après cid: doivent correspondre exactement. Les images intégrées alourdissent le message pour chaque destinataire : pour les logos et les autres images communes, une URL d’image hébergée dans le HTML est généralement le meilleur choix.

Limites de taille

L’encodage base64 grossit les fichiers d’environ un tiers, et la limite de 40 Mo s’applique au message encodé. En pratique, gardez la taille totale de vos fichiers sous 29 Mo environ. Au-delà, déposez le fichier sur votre propre stockage et envoyez un lien.

Types de fichiers autorisés

filename doit se terminer par l’une de ces extensions. Toute autre extension, ou un nom sans extension, fait échouer la validation avec 400.

Les fichiers exécutables et les scripts ne figurent pas dans la liste et ne peuvent pas être joints.

Lire les pièces jointes d’un e-mail envoyé

Lister les pièces jointes (GET /emails/{id}/attachments) renvoie chaque pièce jointe avec son filename, son content_type, sa size, son content_id, sa content_disposition (attachment ou inline) et son content en base64. Cet endpoint nécessite une clé Full Access. Les pièces jointes sont supprimées en même temps que le contenu des messages à la fin de votre période de conservation des données.

Dépannage

Voir aussi

• Envoyer un e-mail
• Envoyer un e-mail dans la référence de l’API
• Conservation des données