# Pièces jointes

> Joignez des fichiers aux e-mails envoyés par l’API en base64 ou depuis une URL, intégrez des images avec un Content-ID, et respectez les types de fichiers autorisés et les limites de taille.

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 :

- `filename` (string, obligatoire): Nom du fichier affiché au destinataire. Il doit se terminer par une [extension autorisée](#allowed-file-types).
- `content` (string): Le fichier encodé en base64. Utilisez soit `content`, soit `url`, pas les deux.
- `url` (string): Une URL `http://` ou `https://` depuis laquelle Emailit télécharge le fichier. Utilisez soit `content`, soit `url`, pas les deux.
- `content_type` (string): Le type MIME, par exemple `application/pdf`. Obligatoire avec `content`. Avec `url`, vaut par défaut le `Content-Type` renvoyé par le serveur.
- `content_id` (string): Un Content-ID. S’il est défini, la pièce jointe devient une image intégrée, que votre HTML peut afficher avec `cid:`.
- `encoding` (string): Encodage de `content`. Laissez `base64` sauf si vous avez une raison de le changer.

## Joindre un fichier en base64

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

**cURL**

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

**Node.js**

```javascript
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',
    },
  ],
});
```

**Python**

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

**PHP**

```php
$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.

```json
{
  "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`.

```json
{
  "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

| Limite | Valeur |
| --- | --- |
| Message complet, après encodage | 40 Mo. Les messages plus volumineux échouent avec `413 Message too large`. |
| Une pièce jointe téléchargée depuis `url` | 25 Mo |
| Timeout de téléchargement pour `url` | 30 secondes |
| Corps de la requête JSON | 50 Mo |

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`.

| Catégorie | Extensions |
| --- | --- |
| Texte | `.txt`, `.csv`, `.log`, `.css`, `.ics`, `.xml` |
| Images | `.jpg`, `.jpe`, `.jpeg`, `.gif`, `.png`, `.bmp`, `.psd`, `.tif`, `.tiff`, `.svg`, `.indd`, `.ai`, `.eps` |
| Documents | `.doc`, `.docx`, `.rtf`, `.odt`, `.ott`, `.pdf`, `.pub`, `.pages`, `.mobi`, `.epub` |
| Audio | `.mp3`, `.m4a`, `.m4v`, `.wma`, `.ogg`, `.flac`, `.wav`, `.aif`, `.aifc`, `.aiff` |
| Vidéo | `.mp4`, `.mov`, `.avi`, `.mkv`, `.mpeg`, `.mpg`, `.wmv` |
| Tableurs | `.xls`, `.xlsx`, `.ods`, `.numbers` |
| Présentations | `.odp`, `.ppt`, `.pptx`, `.pps`, `.key` |
| Archives et contacts | `.zip`, `.vcf` |
| E-mail | `.eml` |
| Signatures et chiffrement | `.p7c`, `.p7m`, `.p7s`, `.pgp`, `.asc`, `.sig` |

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](/fr/docs/api-reference/emails/attachments/) (`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](/fr/docs/data-retention/).

## Dépannage

| Erreur | À vérifier |
| --- | --- |
| `Attachment at index 0 missing content_type (required when using 'content')` | Ajoutez `content_type` à chaque pièce jointe en base64. |
| `Attachment 'report.exe' has unsupported file type '.exe'` | Utilisez une extension autorisée, ou placez le fichier dans un `.zip`. |
| `Attachment at index 0 cannot have both 'content' and 'url'` | Envoyez l’un des deux. |
| `Attachment error` avec `Failed to fetch attachment` | L’URL a renvoyé un statut d’erreur, a redirigé, a expiré (timeout) ou n’est pas publique. Ouvrez-la depuis un serveur extérieur à votre réseau pour vérifier. |
| `Attachment error` avec `Attachment too large (max 25MB)` | Hébergez le fichier et envoyez plutôt un lien. |
| `413 Message too large` | Réduisez la taille totale des pièces jointes. |

## Voir aussi

- [Envoyer un e-mail](/fr/docs/email-api/send-email/)
- [Envoyer un e-mail](/fr/docs/api-reference/emails/send/) dans la référence de l’API
- [Conservation des données](/fr/docs/data-retention/)

---
Source: https://emailit.com/fr/docs/email-api/attachments/