Pièces jointes
Joignez des fichiers à un envoi en ajoutant un tableau attachments au payload POST /v1/email/messages. Chaque entrée contient les octets du fichier encodés en base64 dans content, ainsi qu'un filename. Le même tableau fonctionne sur un élément de lot. Les schémas complets de requête et de réponse se trouvent dans la référence API.
Un envoi avec une pièce jointe
await bird.email.send({
from: "hello@yourdomain.com",
to: ["delivered@messagebird.dev"],
subject: "Your invoice",
html: "<p>Thanks for your order. Your invoice is attached.</p>",
attachments: [
{
filename: "invoice.pdf",
content: "JVBERi0xLjcKJ...",
content_type: "application/pdf",
},
],
});client.email.send(
from_="hello@yourdomain.com",
to=["delivered@messagebird.dev"],
subject="Your invoice",
html="<p>Thanks for your order. Your invoice is attached.</p>",
attachments=[
{
"filename": "invoice.pdf",
"content": "JVBERi0xLjcKJ...",
"content_type": "application/pdf",
}
],
)_, err := client.Email.Send(context.Background(), bird.EmailSendParams{
From: "hello@yourdomain.com",
To: []string{"delivered@messagebird.dev"},
Subject: "Your invoice",
HTML: "<p>Thanks for your order. Your invoice is attached.</p>",
Attachments: []bird.EmailAttachment{{
Filename: "invoice.pdf",
Content: pdfBytes,
ContentType: bird.String("application/pdf"),
}},
})$bird->email->send(
from: 'hello@yourdomain.com',
to: ['delivered@messagebird.dev'],
subject: 'Your invoice',
html: '<p>Thanks for your order. Your invoice is attached.</p>',
attachments: [
(new EmailAttachment())
->setFilename('invoice.pdf')
->setContent('JVBERi0xLjcKJ...')
->setContentType('application/pdf'),
],
);bird email send \
--from hello@yourdomain.com \
--to delivered@messagebird.dev \
--subject 'Your invoice' \
--html '<p>Thanks for your order. Your invoice is attached.</p>' \
--attach ./invoice.pdfcurl -X POST https://us1.platform.bird.com/v1/email/messages \
-H "Authorization: Bearer bk_us1_..." \
-H "Content-Type: application/json" \
-d '{
"from": "hello@yourdomain.com",
"to": ["delivered@messagebird.dev"],
"subject": "Your invoice",
"html": "<p>Thanks for your order. Your invoice is attached.</p>",
"attachments": [
{
"filename": "invoice.pdf",
"content": "JVBERi0xLjcKJ...",
"content_type": "application/pdf"
}
]
}'Le CLI lit le fichier et l'encode en base64 pour vous ; via l'API, vous fournissez les octets encodés vous-même. Le SDK Go prend les octets bruts et les encode lors de la transmission.
content contient les octets bruts du fichier, encodés en base64. content_type est facultatif : si vous l'omettez, le type MIME est déduit de l'extension filename, avec un repli sur application/octet-stream pour les extensions non reconnues. Tout le reste de l'envoi fonctionne exactement comme dans l'envoi d'e-mails : le 202, le modèle asynchrone, les tags et les métadonnées ne changent pas en présence de pièces jointes.
Les champs de pièce jointe
| Champ | Type | Requis | Remarques |
|---|---|---|---|
| filename | string | oui | 1 à 255 caractères ; affiché au destinataire. Pas de sauts de ligne ni de caractères de contrôle. |
| content | string | oui | Octets du fichier encodés en Base64. |
| content_type | string | non | Type MIME ; déduit de l'extension du nom de fichier si omis. |
| content_id | string | non | 1 à 128 caractères, [A-Za-z0-9._-]. Définissez-le pour afficher le fichier intégré au lieu de joint. |
Un e-mail peut contenir jusqu'à 20 pièces jointes (attachments est limité à 20 éléments).
Images intégrées
Pour intégrer une image dans le corps HTML plutôt que de la joindre, attribuez un content_id à la pièce jointe et référencez-la dans le balisage avec une URL cid: :
Exemple de code
{
"html": "<p>Welcome aboard!</p><img src=\"cid:welcome-banner\"/>",
"attachments": [
{
"filename": "banner.png",
"content": "iVBORw0KGgoAAAANS...",
"content_type": "image/png",
"content_id": "welcome-banner"
}
]
}Le content_id est le lien entre la référence cid: et la pièce jointe. Chaque image intégrée doit avoir un content_id unique dans l'envoi ; un doublon est rejeté avec une 422. Une pièce jointe sans content_id est livrée comme une pièce jointe classique.
Budget de taille
Nous rejetons un envoi dont la taille estimée du message généré dépasse 20 Mo avec une 413. L'estimation correspond au corps HTML plus le corps texte plus chaque pièce jointe mesurée après l'encodage base64. L'encodage augmente les octets bruts d'environ 4/3, donc un fichier de 15 Mo consomme déjà à lui seul la totalité du budget de 20 Mo. En règle générale, maintenez le contenu brut total des pièces jointes bien en dessous de 15 Mo pour que les corps et l'enveloppe MIME puissent encore tenir.
Les serveurs de réception peuvent appliquer des limites de taille inférieures. Un message accepté par Bird peut quand même rebondir si le serveur du destinataire rejette sa taille. Choisissez la taille des pièces jointes en fonction des fournisseurs de messagerie et des organisations auxquels vous envoyez.
Pour les messages reçus, consultez Taille des messages entrants.
Types de fichiers bloqués
Les pièces jointes exécutables et de script sont rejetées lors de la validation avec une 422, en fonction du content_type ou de l'extension du nom de fichier. Les extensions bloquées incluent .exe, .dll, .msi, .bat, .cmd, .scr, .jar, .js, .vbs, .ps1, .sh, .hta et .lnk. Les types MIME équivalents tels que application/x-msdownload, application/java-archive et text/javascript sont également bloqués. Cette validation n'est pas un antivirus. Pour distribuer un fichier bloqué, hébergez-le derrière un lien.
Dans un lot
Chaque élément d'un envoi par lot peut avoir son propre attachments, avec le même contrat de champs et le même budget de 20 Mo par message. Le corps sérialisé de la requête du lot a sa propre limite en plus, que les pièces jointes encodées en base64 consomment rapidement ; consultez l'envoi par lot pour la limite au niveau du lot et comment la contourner.
Lecture et téléchargement des pièces jointes
Les lectures API ne renvoient jamais les octets des pièces jointes. GET /v1/email/messages/{message_id} retourne un tableau attachments de métadonnées uniquement ; chaque entrée contient le id, le filename, le content_type, la size (octets décodés) et le inline de la pièce jointe :
Exemple de code
{
"attachments": [
{
"id": "ea_019c...",
"filename": "invoice.pdf",
"content_type": "application/pdf",
"size": 215432,
"inline": false
}
]
}Pour récupérer les octets bruts, appelez GET /v1/email/messages/{message_id}/attachments/{attachment_id} (référence). Le fichier est transmis en flux avec son propre type de contenu et un en-tête Content-Disposition indiquant le nom du fichier. Deux conditions s'appliquent :
- Le stockage du contenu doit être activé pour l'espace de travail. Si le stockage est désactivé, rien n'est conservé pour le téléchargement. Consultez ce que signifie un 202.
- Les pièces jointes sont conservées pendant 30 jours après l'envoi. Passé ce délai, le téléchargement retourne 410 Gone.
Un 404 signifie que le message n'a pas de contenu stocké ou pas de pièce jointe avec cet ID ; un 425 Too Early signifie que la pièce jointe est encore en cours de stockage et que la requête peut être réessayée dans un instant.
Étapes suivantes
- Envoi d'e-mails : le reste du payload d'envoi, y compris les destinataires, le contenu, les tags et le modèle asynchrone
- Envoi par lot : les lots et la place des pièces jointes dans de nombreux messages
- Référence API : créer un message : le schéma complet de requête, y compris attachments
- Référence API : télécharger une pièce jointe : le point de terminaison de récupération et ses codes de statut
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.
Regarder le guideGetting started with emailExplorer la fonctionnalitéEmailSuivre le parcours d'apprentissageBuild your first integrationGuide d'implémentationSend your first email
Essayez la pratique et obtenez un guide d'implémentation