Send with Attachments

You can send transactional emails with one or more file attachments using the thePurplebox API.
This is useful for delivering invoices, reports, receipts, or any other documents generated by your application.

Prerequisites

A thePurplebox account
A secret API key generated from your dashboard
A verified sending domain (recommended for best deliverability)

Parameters

When sending an email with attachments, include the following in your request:

to — A single email address or array of recipient emails
subject — The email subject line
body — Plain text or HTML content for the email body
attachments — An array of attachment objects (up to 5 files):
- filename — The name of the file as it will appear to the recipient
- content — Base64-encoded file data
- contentType — MIME type (e.g., application/pdf, image/png)

Important Notes

You can attach up to 5 files per email
The content field must be base64 encoded
Maximum attachment size per file is 5MB
Total email size (including all attachments) must not exceed 25MB

Example Requests

await fetch('https://api.thepurplebox.io/v1/send', {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API_KEY>"
  },
  body: JSON.stringify({
    to: "[email protected]",
    subject: "Your requested document",
    body: "Please find the attached file.",
    attachments: [
      {
        filename: "document.pdf",
        content: "<BASE64_ENCODED_CONTENT>",
        contentType: "application/pdf"
      }
    ]
  })
})

package main

import (
	"bytes"
	"encoding/json"
	"net/http"
)

func main() {
	payload := map[string]interface{}{
		"to":      "[email protected]",
		"subject": "Your requested document",
		"body":    "Please find the attached file.",
		"attachments": []map[string]string{
			{
				"filename":    "document.pdf",
				"content":     "<BASE64_ENCODED_CONTENT>",
				"contentType": "application/pdf",
			},
		},
	}

	jsonData, _ := json.Marshal(payload)
	req, _ := http.NewRequest("POST", "https://api.thepurplebox.io/v1/send", bytes.NewBuffer(jsonData))
	req.Header.Set("Authorization", "Bearer <API_KEY>")
	req.Header.Set("Content-Type", "application/json")

	client := &http.Client{}
	client.Do(req)
}

import requests

url = "https://api.thepurplebox.io/v1/send"

payload = {
    "to": "[email protected]",
    "subject": "Your requested document",
    "body": "Please find the attached file.",
    "attachments": [
        {
            "filename": "document.pdf",
            "content": "<BASE64_ENCODED_CONTENT>",
            "contentType": "application/pdf"
        }
    ]
}

headers = {
    "Authorization": "Bearer <API_KEY>",
    "Content-Type": "application/json"
}

requests.post(url, json=payload, headers=headers)

<?php

$url = "https://api.thepurplebox.io/v1/send";

$payload = [
    "to" => "[email protected]",
    "subject" => "Your requested document",
    "body" => "Please find the attached file.",
    "attachments" => [
        [
            "filename" => "document.pdf",
            "content" => "<BASE64_ENCODED_CONTENT>",
            "contentType" => "application/pdf"
        ]
    ]
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer <API_KEY>",
    "Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);
?>

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;

public class SendEmail {
    public static void main(String[] args) throws Exception {
        String json = """
        {
            "to": "[email protected]",
            "subject": "Your requested document",
            "body": "Please find the attached file.",
            "attachments": [
                {
                    "filename": "document.pdf",
                    "content": "<BASE64_ENCODED_CONTENT>",
                    "contentType": "application/pdf"
                }
            ]
        }
        """;

        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.thepurplebox.io/v1/send"))
            .header("Content-Type", "application/json")
            .header("Authorization", "Bearer <API_KEY>")
            .POST(HttpRequest.BodyPublishers.ofString(json))
            .build();

        HttpResponse<String> response = client.send(request, 
            HttpResponse.BodyHandlers.ofString());
    }
}

require 'net/http'
require 'json'
require 'uri'

uri = URI('https://api.thepurplebox.io/v1/send')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri)
request['Content-Type'] = 'application/json'
request['Authorization'] = 'Bearer <API_KEY>'

request.body = {
  to: '[email protected]',
  subject: 'Your requested document',
  body: 'Please find the attached file.',
  attachments: [
    {
      filename: 'document.pdf',
      content: '<BASE64_ENCODED_CONTENT>',
      contentType: 'application/pdf'
    }
  ]
}.to_json

response = http.request(request)

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

public class SendEmail
{
    public static async Task Main()
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer <API_KEY>");

        var payload = new
        {
            to = "[email protected]",
            subject = "Your requested document",
            body = "Please find the attached file.",
            attachments = new[]
            {
                new
                {
                    filename = "document.pdf",
                    content = "<BASE64_ENCODED_CONTENT>",
                    contentType = "application/pdf"
                }
            }
        };

        var json = JsonSerializer.Serialize(payload);
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        var response = await client.PostAsync(
            "https://api.thepurplebox.io/v1/send", 
            content
        );
    }
}

using Microsoft.AspNetCore.Mvc;
using System.Net.Http;
using System.Text;
using System.Text.Json;

[ApiController]
[Route("api/[controller]")]
public class EmailController : ControllerBase
{
    private readonly IHttpClientFactory _httpClientFactory;

    public EmailController(IHttpClientFactory httpClientFactory)
    {
        _httpClientFactory = httpClientFactory;
    }

    [HttpPost("send-with-attachment")]
    public async Task<IActionResult> SendEmailWithAttachment()
    {
        var client = _httpClientFactory.CreateClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer <API_KEY>");

        var payload = new
        {
            to = "[email protected]",
            subject = "Your requested document",
            body = "Please find the attached file.",
            attachments = new[]
            {
                new
                {
                    filename = "document.pdf",
                    content = "<BASE64_ENCODED_CONTENT>",
                    contentType = "application/pdf"
                }
            }
        };

        var json = JsonSerializer.Serialize(payload);
        var content = new StringContent(json, Encoding.UTF8, "application/json");

        var response = await client.PostAsync(
            "https://api.thepurplebox.io/v1/send", 
            content
        );

        if (response.IsSuccessStatusCode)
        {
            return Ok(new { message = "Email sent successfully" });
        }

        return BadRequest(new { message = "Failed to send email" });
    }
}

curl -X POST https://api.thepurplebox.io/v1/send \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "to": "[email protected]",
    "subject": "Your requested document",
    "body": "Please find the attached file.",
    "attachments": [
      {
        "filename": "document.pdf",
        "content": "<BASE64_ENCODED_CONTENT>",
        "contentType": "application/pdf"
      }
    ]
  }'

Get Started

Guides

Tools

Configuration

Prerequisites

Parameters

Important Notes

Example Requests

Get Started

Guides

Tools

Configuration

​Prerequisites

​Parameters

​Important Notes

​Example Requests

Prerequisites

Parameters

Important Notes

Example Requests