Skip to main content

Attachments​

Email API supports adding file attachments to emails using the attachments array in the JSON payload.

Attachment Structure​

Each attachment is represented by an object with the following properties:

{
  "type": "MIME type",
  "filename": "file name",
  "content": "Base64 encoded content"
}
  • type: MIME type of the file (e.g., "image/png", "application/pdf")
  • filename: Name of the file as it will appear to the recipient
  • content: Base64 encoded file content

Usage Notes​

  • Multiple attachments can be included in a single email
  • Maximum of 1000 attachments per email
  • Combined size limit (attachments + email content) is 30MB
  • Base64 encoding is required for all attachment content
info

If your email message exceeds the size limit, it will be rejected with an error.

info

Base64 encoding increases the data required for an attachment by about 33% over binary encoding. Be sure to check the size of your attachments after base64 encoding.

Example: Email with Attachment​

{
  "personalizations": [
    {
      "to": [{ "email": "recipient@example.com", "name": "Recipient Name" }]
    }
  ],
  "from": { "email": "sender@example.com", "name": "Sender Name" },
  "subject": "Email with Attachment",
  "content": [
    { "type": "text/plain", "value": "Please see the attached image." },
    { "type": "text/html", "value": "<html><body><p>Please see the attached image.</p></body></html>" }
  ],
  "attachments": [
    {
      "type": "image/png",
      "filename": "logo.png",
      "content": "iVBORw0KGgoAAAANSUhEUgAAAKIAAA... (truncated for brevity)"
    }
  ]
}

Implementation Examples​

curl -X POST "https://api.mailchannels.net/tx/v1/send" \
  -H 'X-Api-Key: YOUR-API-KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "personalizations": [
      {
        "to": [{ "email": "recipient@example.com", "name": "Recipient Name" }]
      }
    ],
    "from": { "email": "sender@example.com", "name": "Sender Name" },
    "subject": "Email with Attachment",
    "content": [
      { "type": "text/plain", "value": "Please see the attached image." },
      { "type": "text/html", "value": "<html><body><p>Please see the attached image.</p></body></html>" }
    ],
    "attachments": [
      {
        "type": "image/png",
        "filename": "logo.png",
        "content": "iVBORw0KGgoAAAANSUhEUgAAAKIAAA... (truncated for brevity)"
      }
    ]
  }'
info

Ensure proper error handling and security measures when implementing attachment functionality in your application. Never send an attachment that you received from a user without first scanning it for viruses and malware.

Appendix: Common MIME Types​

When adding attachments to your email, it is essential to specify the correct MIME type for the file. Below is a list of common MIME types for various file types:

Image Files​

File TypeMIME Type
JPEG Imageimage/jpeg
PNG Imageimage/png
GIF Imageimage/gif
BMP Imageimage/bmp
SVG Imageimage/svg+xml

Document Files​

File TypeMIME Type
PDF Documentapplication/pdf
Microsoft Wordapplication/msword
Microsoft Excelapplication/vnd.ms-excel
Microsoft PowerPointapplication/vnd.ms-powerpoint
Plain Texttext/plain
HTML Documenttext/html

Audio Files​

File TypeMIME Type
MP3 Audioaudio/mpeg
WAV Audioaudio/wav
OGG Audioaudio/ogg

Video Files​

File TypeMIME Type
MP4 Videovideo/mp4
AVI Videovideo/x-msvideo
WebM Videovideo/webm

Compressed Files​

File TypeMIME Type
ZIP Archiveapplication/zip
GZIP Archiveapplication/gzip
7-Zip Archiveapplication/x-7z-compressed

Other Common MIME Types​

File TypeMIME Type
JSONapplication/json
XMLapplication/xml
CSVtext/csv

Ensure to select the appropriate MIME type for each file to avoid any issues with email delivery.

Appendix: Auto-Detecting MIME Types​

Here are examples in Go and JavaScript that illustrate how you can detect the MIME type of an attachment automatically:

Go Code Sample (Using net/http and mime packages)​

In Go, you can use the net/http package to detect the MIME type of a file based on its content. Here's a simple example:

package main

import (
	"encoding/base64"
	"fmt"
	"io/ioutil"
	"mime"
	"net/http"
	"path/filepath"
)

func detectMimeType(filePath string) (string, error) {
	// Read the file content
	data, err := ioutil.ReadFile(filePath)
	if err != nil {
		return "", err
	}

	// Detect MIME type based on file content
	mimeType := http.DetectContentType(data)

	return mimeType, nil
}

func main() {
	filePath := "path/to/your/file.png" // Change this to the path of your file

	// Detect MIME type
	mimeType, err := detectMimeType(filePath)
	if err != nil {
		fmt.Println("Error detecting MIME type:", err)
		return
	}

	// Convert file content to Base64
	fileContent, err := ioutil.ReadFile(filePath)
	if err != nil {
		fmt.Println("Error reading file:", err)
		return
	}

	encodedContent := base64.StdEncoding.EncodeToString(fileContent)

	// Get the filename
	fileName := filepath.Base(filePath)

	fmt.Printf("MIME Type: %s\nFilename: %s\nBase64 Content: %s\n", mimeType, fileName, encodedContent)
}