Pièces jointes

Joindre une facture, un contrat ou une image à vos emails.

Forfait requis

Les pièces jointes sont incluses dans les forfaits Pro et Agency (ainsi qu'Enterprise). Sur un autre forfait, toute requête contenant une pièce jointe est refusée avec un message explicite.

Deux façons d'envoyer un fichier

Choisissez celle qui correspond à l'endroit où se trouve votre fichier : sur le disque du serveur qui appelle l'API (multipart), ou déjà en mémoire / encodé (JSON).

1. Upload direct (multipart/form-data)

C'est la forme la plus simple avec cURL : préfixez le chemin du fichier par @.

bash

curl -X POST "https://mailer.echange.online/api/send.php" \
  -H "X-API-Key: VOTRE_CLE_API" \
  -F "to=client@example.com" \
  -F "from=facturation@mondomaine.com" \
  -F "subject=Votre facture de janvier" \
  -F "body=Bonjour, votre facture est en pièce jointe." \
  -F "attachments[]=@/chemin/vers/facture-2026-01.pdf"

Plusieurs fichiers : répétez le champ attachments[].

bash

  -F "attachments[]=@/chemin/vers/facture.pdf" \
  -F "attachments[]=@/chemin/vers/conditions.pdf"

Attention

Avec -F, cURL bascule en multipart/form-data : tous les autres paramètres doivent alors aussi être passés en -F, et non en -d. Mélanger les deux ne fonctionne pas.

2. Contenu encodé en base64 (application/json)

Pratique quand le fichier est généré à la volée (un PDF construit en mémoire, par exemple) :

json

{
  "to": "client@example.com",
  "from": "facturation@mondomaine.com",
  "subject": "Votre facture de janvier",
  "body": "Bonjour, votre facture est en pièce jointe.",
  "attachments": [
    {
      "filename": "facture-2026-01.pdf",
      "content_type": "application/pdf",
      "content_base64": "JVBERi0xLjQKJeLjz9MKMy..."
    }
  ]
}

Champ	Obligatoire	Description
`filename`	oui	Nom du fichier tel qu'il apparaîtra chez le destinataire.
`content_base64`	oui	Contenu du fichier encodé en base64.
`content_type`	non	Type MIME. S'il est absent, il est déduit de l'extension puis, à défaut, du contenu du fichier.

Limites

Forfait	Pièces jointes par email	Taille cumulée
Gratuit, Basic, Team	—	non disponible
Pro	5	10 Mo
Agency	10	20 Mo
Enterprise	20	25 Mo

Attention

Ces tailles sont mesurées avant encodage MIME. L'encodage base64 ajoute environ 33 % au message transmis : une pièce jointe de 10 Mo produit un message d'environ 13,5 Mo. Or beaucoup de serveurs de réception refusent au-delà de 10 à 25 Mo. Au-delà de quelques mégaoctets, préférez un lien de téléchargement dans le corps du message : c'est plus fiable, et vos destinataires ne verront pas leur boîte saturer.

Types de fichiers refusés

Les fichiers exécutables sont systématiquement refusés, quel que soit le forfait : le service ne doit pas devenir un vecteur de distribution de binaires, et ces pièces jointes sont de toute façon bloquées par la quasi-totalité des serveurs de réception.

.exe .dll .bat .cmd .com .msi .scr .vbs .js .jar .ps1 .reg .lnk .iso et une trentaine d'autres extensions du même type.

Pour transmettre malgré tout un exécutable, placez-le dans une archive protégée par mot de passe (.zip), et communiquez le mot de passe par un autre canal.

Exemple complet en PHP

php

<?php
$ch = curl_init('https://mailer.echange.online/api/send.php');

curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['X-API-Key: ' . getenv('MAIL_SENDER_KEY')],
    CURLOPT_POSTFIELDS => [
        'to' => 'client@example.com',
        'from' => 'facturation@mondomaine.com',
        'subject' => 'Votre facture',
        'format' => 'html',
        'body' => '<p>Bonjour, votre facture est en pièce jointe.</p>',
        // CURLFile bascule automatiquement la requête en multipart/form-data
        'attachments[]' => new CURLFile('/var/factures/2026-01.pdf', 'application/pdf', 'facture-2026-01.pdf'),
    ],
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

if (empty($response['success'])) {
    throw new RuntimeException($response['error']['message'] ?? 'Envoi impossible');
}

Exemple en Python

python

import os
import requests

with open("facture-2026-01.pdf", "rb") as fichier:
    reponse = requests.post(
        "https://mailer.echange.online/api/send.php",
        headers={"X-API-Key": os.environ["MAIL_SENDER_KEY"]},
        data={
            "to": "client@example.com",
            "from": "facturation@mondomaine.com",
            "subject": "Votre facture",
            "body": "Bonjour, votre facture est en pièce jointe.",
        },
        files={"attachments[]": ("facture-2026-01.pdf", fichier, "application/pdf")},
        timeout=30,
    )

reponse.raise_for_status()
print(reponse.json())

Ce que renvoie l'API

json

{
  "success": true,
  "message_id": "<9f2c...@mondomaine.com>",
  "format": "html",
  "recipients": { "to": 1, "cc": 0, "bcc": 0 },
  "attachments": { "count": 1, "bytes": 184320 },
  "quota": { "used": 42, "quota": 20000 }
}

Les fichiers ne sont jamais stockés par le service : ils sont encodés dans le message puis oubliés. Seuls le nombre et la taille cumulée des pièces jointes sont conservés dans le journal d'envoi.