Attachments

Emails can carry files: PDFs, images, spreadsheets and so on. This page explains how to:

Find the attachments of an email
Download an attachment
Show inline images (images inside the email body)
Send an email with attachments
Forward attachments

1. Find the attachments of an email

Attachments are listed inside every email object, in the attachments array. You get them when you list emails or retrieve an email.

curl "$EE_URL/api/v1/emails/email_94a0d77db739407e932c3b97fef44aac" \
  -H "X-API-KEY: $EE_KEY"

Response (part of it)

{
  "object": "Email",
  "id": "email_94a0d77db739407e932c3b97fef44aac",
  "subject": "Q3 report",
  "has_attachments": true,
  "attachments": [
    {
      "id": "att_6f2e8c1a0d4b4f7e9a512c3b8d7e1f00",
      "name": "report.pdf",
      "extension": "pdf",
      "size": 4296429,
      "mime": "application/pdf",
      "cid": null,
      "inline": false
    },
    {
      "id": "att_81c4b2d95e6f4a1b8c7d9e0f1a2b3c4d",
      "name": "logo.png",
      "extension": "png",
      "size": 3120,
      "mime": "image/png",
      "cid": "logo@acme",
      "inline": true
    }
  ]
}

The attachment object

string

The attachment’s att_… id. Use it with the email’s id to download the file.

string

The file name, for example report.pdf. Can be empty if the sender didn’t give one.

string

The file extension, taken from the name, for example pdf. Empty when the name has none.

integer

Size in bytes. 4296429 is about 4.1 MB.

string

The file type (MIME type), for example application/pdf, image/png, text/csv.

string | null

The Content-ID. Only set for images that are shown inside the email body. See Show inline images.

boolean

true: the file is shown inside the email body (usually a logo or a signature image). false: a normal attachment, shown as a file under the email.

Most apps show only the attachments with inline: false in their attachment list, and use the inline: true ones to display the body.

Find emails that have attachments

Add has_attachments=true when you list emails:

curl "$EE_URL/api/v1/emails?account_id=acc_ba1fa6938d8548298e8ce62e4b4b4e99&has_attachments=true" \
  -H "X-API-KEY: $EE_KEY"

You can combine it with any other filter, for example folder=INBOX or from=ana@example.com.

2. Download an attachment

GET /api/v1/emails/{email_id}/attachments/{attachment_id}

string

required

The email’s email_… id.

string

required

The attachment’s att_… id, from the email’s attachments array.

The response is the file itself (binary data), not JSON. Save it as a file, or send it on to your user’s browser. It comes with these headers:

Header	Example	What it tells you
`Content-Type`	`application/pdf`	The file type, the same as the attachment’s `mime`
`Content-Disposition`	`attachment; filename="report.pdf"`	The original file name, so a browser saves it under that name
`Content-Length`	`4296429`	The size in bytes

Examples

# -o saves the response to a file
curl "$EE_URL/api/v1/emails/email_94a0d77db739407e932c3b97fef44aac/attachments/att_6f2e8c1a0d4b4f7e9a512c3b8d7e1f00" \
  -H "X-API-KEY: $EE_KEY" \
  -o report.pdf

import { writeFile } from "node:fs/promises";

const emailId = "email_94a0d77db739407e932c3b97fef44aac";
const attachmentId = "att_6f2e8c1a0d4b4f7e9a512c3b8d7e1f00";

const res = await fetch(`${process.env.EE_URL}/api/v1/emails/${emailId}/attachments/${attachmentId}`, {
  headers: { "X-API-KEY": process.env.EE_KEY },
});
if (!res.ok) throw new Error(`Download failed: ${res.status} ${await res.text()}`);

await writeFile("report.pdf", Buffer.from(await res.arrayBuffer()));

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Storage;

$emailId = 'email_94a0d77db739407e932c3b97fef44aac';
$attachmentId = 'att_6f2e8c1a0d4b4f7e9a512c3b8d7e1f00';

$response = Http::withHeaders(['X-API-KEY' => config('services.email_engine.key')])
    ->get(config('services.email_engine.url')."/api/v1/emails/{$emailId}/attachments/{$attachmentId}")
    ->throw();

Storage::put('attachments/report.pdf', $response->body());

import os, requests

email_id = "email_94a0d77db739407e932c3b97fef44aac"
attachment_id = "att_6f2e8c1a0d4b4f7e9a512c3b8d7e1f00"

r = requests.get(
    f"{os.environ['EE_URL']}/api/v1/emails/{email_id}/attachments/{attachment_id}",
    headers={"X-API-KEY": os.environ["EE_KEY"]},
)
r.raise_for_status()
with open("report.pdf", "wb") as f:
    f.write(r.content)

Let your users download files

Your access token must stay on your server, so your users’ browsers can’t call the engine directly. Instead, add a route in your own app that downloads the file from the engine and passes it on:

Laravel route

Route::get('/emails/{email}/attachments/{attachment}', function (string $email, string $attachment) {
    // Check here that the signed-in user may see this email.
    $r = Http::withHeaders(['X-API-KEY' => config('services.email_engine.key')])
        ->get(config('services.email_engine.url')."/api/v1/emails/{$email}/attachments/{$attachment}")
        ->throw();

    return response($r->body(), 200, [
        'Content-Type' => $r->header('Content-Type'),
        'Content-Disposition' => $r->header('Content-Disposition'),
    ]);
})->middleware('auth');

Errors

Status	`type`	Why
404	`errors/not_found`	No email with this `email_id`, or no attachment with this `attachment_id` in that email. Ids without the right prefix (`email_…`, `att_…`) are not found either
404	`errors/not_found`	The email was permanently deleted (emptied from Trash). Emails in Trash still work
401	`errors/invalid_credentials`	The file had to be fetched from the provider, and the account’s access was revoked. Reconnect the account
502	`errors/provider_error`	The file had to be fetched from the provider, and the provider didn’t answer. Try again later

See Errors for the error format.

Where the file comes from

You don’t need to do anything for this. It explains why downloads are fast and keep working.

New emails are saved right away, without the files. The engine saves the email and the list of its attachments (name, size, type) first, so a large file never delays new mail or webhooks.
A background job then copies every file into your workspace’s storage, a few seconds later.
Downloads come from that copy. They’re fast, and they work even when the IMAP server is slow or down.
If you download a file before it’s copied, the engine gets it from the provider for you and copies it at the same time.

3. Show inline images

Some emails show images inside the text, for example a company logo in a signature. Those images are sent as attachments with inline: true, and the HTML body points to them with a cid: link instead of a normal URL:

<p>Best regards,</p>
<img src="cid:logo@acme" alt="Acme">

A browser can’t open cid:logo@acme, so the image looks broken if you display the body as it is. To fix it, replace each cid: link with a URL that serves the attachment, such as your own download route:

Find the inline attachments

Take the attachments that have a cid, for example { "id": "att_81c4b2d95e6f4a1b8c7d9e0f1a2b3c4d", "cid": "logo@acme" }.

Replace each cid: link in the body

Replace cid:logo@acme with your URL for that attachment, for example /emails/email_94a0d77db739407e932c3b97fef44aac/attachments/att_81c4b2d95e6f4a1b8c7d9e0f1a2b3c4d.

Display the body

The images now load from your app.

Node.js

function showInlineImages(email) {
  let html = email.body;
  for (const a of email.attachments) {
    if (!a.cid) continue;
    const url = `/emails/${email.id}/attachments/${a.id}`; // your own route
    html = html.replaceAll(`cid:${a.cid}`, url);
  }
  return html;
}

Email HTML comes from outside senders. Clean it with an HTML sanitizer (for example DOMPurify) before you display it, and show it in a sandboxed iframe.

4. Send an email with attachments

Use Send an email (POST /api/v1/emails) and add the files in one of two ways.

Option A: multipart/form-data (upload files)

Best when you have the files on disk or from an upload form. Put each file in a field named attachments, and repeat the field for more files. The other fields (account_id, to, subject, body …) are normal text fields.

curl -X POST "$EE_URL/api/v1/emails" \
  -H "X-API-KEY: $EE_KEY" \
  -F account_id=acc_ba1fa6938d8548298e8ce62e4b4b4e99 \
  -F 'to=[{"identifier":"ana@example.com"}]' \
  -F subject="Our proposal" \
  -F body="<p>Hi Ana, the proposal and price list are attached.</p>" \
  -F 'attachments=@proposal.pdf;type=application/pdf' \
  -F 'attachments=@prices.xlsx;type=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("account_id", "acc_ba1fa6938d8548298e8ce62e4b4b4e99");
form.append("to", JSON.stringify([{ identifier: "ana@example.com" }]));
form.append("subject", "Our proposal");
form.append("body", "<p>Hi Ana, the proposal is attached.</p>");
form.append("attachments", new Blob([await readFile("proposal.pdf")], { type: "application/pdf" }), "proposal.pdf");

const res = await fetch(`${process.env.EE_URL}/api/v1/emails`, {
  method: "POST",
  headers: { "X-API-KEY": process.env.EE_KEY }, // don't set Content-Type: fetch adds it for FormData
  body: form,
});
console.log(await res.json());

$response = Http::withHeaders(['X-API-KEY' => config('services.email_engine.key')])
    ->attach('attachments', file_get_contents('proposal.pdf'), 'proposal.pdf', ['Content-Type' => 'application/pdf'])
    ->post(config('services.email_engine.url').'/api/v1/emails', [
        'account_id' => 'acc_ba1fa6938d8548298e8ce62e4b4b4e99',
        'to' => json_encode([['identifier' => 'ana@example.com']]),
        'subject' => 'Our proposal',
        'body' => '<p>Hi Ana, the proposal is attached.</p>',
    ]);

In a multipart request, to, cc and bcc can be a JSON list (as above) or simply ana@example.com, bob@example.com.

Option B: JSON (base64 content)

Best when the file is already in memory, for example generated by your app. Send the file content encoded as base64:

object[]

One object per file.

string

default:"attachment"

The name the recipient sees, for example proposal.pdf.

string

default:"application/octet-stream"

The file type, for example application/pdf.

string

required

The file content, base64-encoded.

curl -X POST "$EE_URL/api/v1/emails" \
  -H "X-API-KEY: $EE_KEY" -H "Content-Type: application/json" \
  -d '{
    "account_id": "acc_ba1fa6938d8548298e8ce62e4b4b4e99",
    "to": [{ "identifier": "ana@example.com" }],
    "subject": "Our proposal",
    "body": "<p>Hi Ana, the proposal is attached.</p>",
    "attachments": [
      { "filename": "proposal.pdf", "content_type": "application/pdf", "content": "JVBERi0xLjQKJ…" }
    ]
  }'

import { readFile } from "node:fs/promises";

const res = await fetch(`${process.env.EE_URL}/api/v1/emails`, {
  method: "POST",
  headers: { "X-API-KEY": process.env.EE_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    account_id: "acc_ba1fa6938d8548298e8ce62e4b4b4e99",
    to: [{ identifier: "ana@example.com" }],
    subject: "Our proposal",
    body: "<p>Hi Ana, the proposal is attached.</p>",
    attachments: [
      {
        filename: "proposal.pdf",
        content_type: "application/pdf",
        content: (await readFile("proposal.pdf")).toString("base64"),
      },
    ],
  }),
});
console.log(await res.json());

$response = Http::withHeaders(['X-API-KEY' => config('services.email_engine.key')])
    ->post(config('services.email_engine.url').'/api/v1/emails', [
        'account_id' => 'acc_ba1fa6938d8548298e8ce62e4b4b4e99',
        'to' => [['identifier' => 'ana@example.com']],
        'subject' => 'Our proposal',
        'body' => '<p>Hi Ana, the proposal is attached.</p>',
        'attachments' => [[
            'filename' => 'proposal.pdf',
            'content_type' => 'application/pdf',
            'content' => base64_encode(file_get_contents('proposal.pdf')),
        ]],
    ]);

Size limits

Limit	Size
One request to the engine (all files + text)	30 MB
Gmail (the whole email)	25 MB
Other providers (IMAP / SMTP)	Set by the provider, often 10 to 25 MB

Base64 makes files about 33% bigger, so a 20 MB file becomes about 27 MB in a JSON request. For large files, use multipart. If the provider refuses the email, you get an error with the provider’s reason in detail (see Errors).

Attachments work the same way for replies (add reply_to) and drafts.

5. Forward attachments

There’s no separate forward call. To forward an email with its files:

Download each attachment of the original email.
Send a new email with those files, and with the original’s text in body.

Node.js

async function forward(email, to) {
  const form = new FormData();
  form.append("account_id", email.account_id);
  form.append("to", to);
  form.append("subject", `Fwd: ${email.subject}`);
  form.append("body", `<p>---------- Forwarded message ----------</p>${email.body}`);

  for (const a of email.attachments.filter((a) => !a.inline)) {
    const res = await fetch(`${process.env.EE_URL}/api/v1/emails/${email.id}/attachments/${a.id}`, {
      headers: { "X-API-KEY": process.env.EE_KEY },
    });
    form.append("attachments", new Blob([await res.arrayBuffer()], { type: a.mime }), a.name || "attachment");
  }

  const res = await fetch(`${process.env.EE_URL}/api/v1/emails`, {
    method: "POST",
    headers: { "X-API-KEY": process.env.EE_KEY },
    body: form,
  });
  return res.json();
}

Questions

Why is has_attachments true, but I only see a logo?

Inline images (inline: true), like a logo in a signature, are attachments too. Filter on inline: false to show only real file attachments.

Can I download an attachment after the user deleted the email?

While the email is in Trash, yes: it’s still an email in the API (with role: "TRASH"), and its attachments download normally. Once it’s permanently deleted (Trash emptied), the email and its attachments are gone from the API and you get 404. If you need to keep a file, download it and store it in your app when you receive the email.new event.

Do webhooks include the files?

No. An email.new event includes the attachment list (id, name, extension, size, mime), not the file content. Download the files you need with the endpoint above.

Is there a limit on how many attachments I can send?

No fixed number. The total request must stay under 30 MB, and under the provider’s own limit.

Getting started

Accounts

Emails

Webhooks

Reference

1. Find the attachments of an email

The attachment object

Find emails that have attachments

2. Download an attachment

Examples

Let your users download files

Errors

Where the file comes from

3. Show inline images

4. Send an email with attachments

Option A: multipart/form-data (upload files)

Option B: JSON (base64 content)

Size limits

5. Forward attachments

Questions

​1. Find the attachments of an email

​The attachment object

​Find emails that have attachments

​2. Download an attachment

​Examples

​Let your users download files

​Errors

​Where the file comes from

​3. Show inline images

​4. Send an email with attachments

​Option A: multipart/form-data (upload files)

​Option B: JSON (base64 content)

​Size limits

​5. Forward attachments

​Questions

1. Find the attachments of an email

The attachment object

Find emails that have attachments

2. Download an attachment

Examples

Let your users download files

Errors

Where the file comes from

3. Show inline images

4. Send an email with attachments

Option A: multipart/form-data (upload files)

Option B: JSON (base64 content)

Size limits

5. Forward attachments

Questions