# Attachments

Attach files to a send by adding an `attachments` array to the `POST /v1/email/messages` payload. Each entry has the file's bytes base64-encoded in `content`, plus a `filename`. The same array works on a [batch](/content/docs/guides/email/sending-bulk/index.html) item. Full request and response schemas are in the [API reference](/content/docs/api/reference/create-email-message/index.html).

## A send with one attachment

### TypeScript
```typescript
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",
    },
  ],
});
```

### Python
```python
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",
        }
    ],
)
```

### Go
```go
_, 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"),
	}},
})
```

### PHP
```php
$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'),
    ],
);
```

### CLI
```cli
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.pdf
```

### cURL
```curl
curl -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"
      }
    ]
  }'
```

The CLI reads the file and base64-encodes it for you; over the API, you supply the encoded bytes yourself. The Go SDK takes the raw bytes and encodes them on the wire.

`content` is the raw file bytes, base64-encoded. `content_type` is optional: when you omit it, we infer the MIME type from the `filename` extension, falling back to `application/octet-stream` for an extension we don't recognize. Everything else about the send works exactly as in [sending email](/content/docs/guides/email/sending-email/index.html): the `202`, the async model, tags, and metadata are unchanged by the presence of attachments.

## The attachment fields

| Field         | Type    | Required | Notes                                                                                |
|---------------|---------|----------|--------------------------------------------------------------------------------------|
| `filename`    | string  | yes      | 1 to 255 characters; shown to the recipient. No line breaks or control characters.   |
| `content`     | string  | yes      | Base64-encoded file bytes.                                                            |
| `content_type`| string  | no       | MIME type; inferred from the filename extension when omitted.                        |
| `content_id`  | string  | no       | 1 to 128 characters, `[A-Za-z0-9._-]`. Set it to render the file inline instead of attached. |

An email can have up to 20 attachments (`attachments` is capped at 20 items).

## Inline images

To embed an image in the HTML body rather than attach it, give the attachment a `content_id` and reference it from the markup with a `cid:` URL:

Code example
```json
{
  "html": "<p>Welcome aboard!</p><img src=\"cid:welcome-banner\"/>",
  "attachments": [
    {
      "filename": "banner.png",
      "content": "iVBORw0KGgoAAAANS...",
      "content_type": "image/png",
      "content_id": "welcome-banner"
    }
  ]
}
```

The `content_id` is the join between the `cid:` reference and the attachment. Each inline image needs a unique `content_id` within the send; a duplicate is rejected with a `422`. An attachment with no `content_id` is delivered as a regular file attachment.

## Size budget

We reject a send whose **estimated generated message size** exceeds **20 MB** with a `413`. The estimate is the HTML body plus the text body plus every attachment measured _after_ base64 encoding. Encoding inflates raw bytes by roughly 4/3, so a 15 MB file already accounts for the whole 20 MB budget on its own. As a rule of thumb, keep total raw attachment content well under **15 MB** so the bodies and the MIME wrapping still fit.

Receiving servers can apply lower size limits. A message that Bird accepts can still bounce if the recipient's server rejects its size. Choose attachment sizes for the mailbox providers and organizations you send to.

## Blocked file types

Executable and script attachments are rejected at validation time with a `422`, based on either `content_type` or the filename extension. Blocked extensions include `.exe`, `.dll`, `.msi`, `.bat`, `.cmd`, `.scr`, `.jar`, `.js`, `.vbs`, `.ps1`, `.sh`, `.hta`, and `.lnk`. Equivalent MIME types such as `application/x-msdownload`, `application/java-archive`, and `text/javascript` are also blocked. This validation is not a virus scanner. To distribute a blocked file, host it behind a link.

## In a batch

Each item in a [batch send](/content/docs/guides/email/sending-bulk/index.html) can have its own `attachments`, with the same field contract and the same per-message 20 MB budget. The batch's serialized request body has its own cap on top, which base64-encoded attachments consume quickly; see [batch sending](/content/docs/guides/email/sending-bulk#attachments-and-the-body-cap/index.html) for the batch-level limit and how to split around it.

## Reading and downloading attachments

API reads never echo attachment bytes. `GET /v1/email/messages/{message_id}` returns an `attachments` array of metadata only; each entry has the attachment `id`, `filename`, `content_type`, `size` (decoded bytes), and `inline`:

Code example
```json
{
  "attachments": [
    {
      "id": "ea_019c...",
      "filename": "invoice.pdf",
      "content_type": "application/pdf",
      "size": 215432,
      "inline": false
    }
  ]
}
```

To get the raw bytes back, call `GET /v1/email/messages/{message_id}/attachments/{attachment_id}` ( [reference](/content/docs/api/reference/get-email-message-attachment/index.html)). It streams the file with its own content type and a `Content-Disposition` header naming the filename. Two conditions gate it:

- **Content storage must be enabled** for the workspace. With storage disabled, nothing is stored to download. See [what a 202 means](/content/docs/guides/email/sending-email#what-a-202-means/index.html).
- **Attachments are retained for 30 days** after the send. After that the download returns `410 Gone`.

A `404` means the message has no stored content or no attachment with that ID; a `425 Too Early` means the attachment is still being stored and the request can be retried in a moment.

## Next steps

- [Sending email](/content/docs/guides/email/sending-email/index.html): the rest of the send payload, including recipients, content, tags, and the async model
- [Batch sending](/content/docs/guides/email/sending-bulk/index.html): batches and where attachments fit across many messages
- [API reference: create a message](/content/docs/api/reference/create-email-message/index.html): the full request schema, including `attachments`
- [API reference: download an attachment](/content/docs/api/reference/get-email-message-attachment/index.html): the retrieval endpoint and its status codes.
