# Custom headers

> Attach custom MIME headers to an email with the headers object.

Add custom MIME headers to an outbound email with the `headers` object — a map of header name to string value. These are written verbatim into the message, which is useful for correlation IDs, threading, or downstream filtering on the receiving side.

MailBlastr already sets all the headers required for deliverability. Custom headers are an advanced feature for a few specific cases — for example, setting a unique **`X-Entity-Ref-ID`** so that Gmail does not collapse a series of distinct messages into a single conversation thread.

## Example

A common use is a per-message reference ID you can correlate against your own systems:

**Node.js**

```js
import { MailBlastr } from 'mailblastr';

const mb = new MailBlastr('mb_xxxxxxxxx');

const { data, error } = await mb.emails.send({
  "from": "Acme <hello@yourdomain.com>",
  "to": ["delivered@example.com"],
  "subject": "Order confirmation",
  "html": "<p>Thanks for your order.</p>",
  "headers": {
    "X-Entity-Ref-ID": "order_12345",
    "X-Mailer-Campaign": "transactional"
  }
});
console.log({ data, error });
```

**Ruby**

```ruby
require "mailblastr"

Mailblastr.api_key = "mb_xxxxxxxxx"

Mailblastr::Emails.send({
  "from": "Acme <hello@yourdomain.com>",
  "to": [
    "delivered@example.com"
  ],
  "subject": "Order confirmation",
  "html": "<p>Thanks for your order.</p>",
  "headers": {
    "X-Entity-Ref-ID": "order_12345",
    "X-Mailer-Campaign": "transactional"
  }
})
```

**PHP**

```php
$mailblastr = Mailblastr::client('mb_xxxxxxxxx');

$mailblastr->emails->send([
  'from' => "Acme <hello@yourdomain.com>",
  'to' => [
    "delivered@example.com"
  ],
  'subject' => "Order confirmation",
  'html' => "<p>Thanks for your order.</p>",
  'headers' => [
    'X-Entity-Ref-ID' => "order_12345",
    'X-Mailer-Campaign' => "transactional"
  ]
]);
```

**Python**

```python
import mailblastr

mailblastr.api_key = "mb_xxxxxxxxx"

mailblastr.Emails.send({
  "from": "Acme <hello@yourdomain.com>",
  "to": [
    "delivered@example.com"
  ],
  "subject": "Order confirmation",
  "html": "<p>Thanks for your order.</p>",
  "headers": {
    "X-Entity-Ref-ID": "order_12345",
    "X-Mailer-Campaign": "transactional"
  }
})
```

**Go**

```go
import "github.com/shekhu10/mailblastr-sdks/mailblastr-go"

client := mailblastr.NewClient("mb_xxxxxxxxx")

params := &mailblastr.SendEmailRequest{
    From:    "Acme <hello@yourdomain.com>",
    To:      []string{"delivered@example.com"},
    Subject: "hello world",
    Html:    "<p>it works!</p>",
}
sent, err := client.Emails.Send(params)
```

**Rust**

```rust
use mailblastr::{Mailblastr, CreateEmailBaseOptions};

let mb = Mailblastr::new("mb_xxxxxxxxx");

let email = CreateEmailBaseOptions::new(
    "Acme <hello@yourdomain.com>",
    ["delivered@example.com"],
    "hello world",
).with_html("<p>it works!</p>");
let _sent = mb.emails.send(email).await?;
```

**Java**

```java
import com.mailblastr.*;

Mailblastr mailblastr = new Mailblastr("mb_xxxxxxxxx");

SendEmailRequest request = SendEmailRequest.builder()
    .from("Acme <hello@yourdomain.com>")
    .to("delivered@example.com")
    .subject("hello world")
    .html("<p>it works!</p>")
    .build();
mailblastr.emails().send(request);
```

**.NET**

```csharp
using Mailblastr;

IMailblastr mailblastr = MailblastrClient.Create("mb_xxxxxxxxx");

var resp = await mailblastr.EmailSendAsync(new EmailMessage
{
    From = "Acme <hello@yourdomain.com>",
    To = "delivered@example.com",
    Subject = "hello world",
    HtmlBody = "<p>it works!</p>",
});
```

**cURL**

```bash
curl -X POST 'https://api.mailblastr.com/emails' \
  -H 'Authorization: Bearer mb_xxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{
  "from": "Acme <hello@yourdomain.com>",
  "to": ["delivered@example.com"],
  "subject": "Order confirmation",
  "html": "<p>Thanks for your order.</p>",
  "headers": {
    "X-Entity-Ref-ID": "order_12345",
    "X-Mailer-Campaign": "transactional"
  }
}'
```

**CLI**

```bash
mailblastr emails send \
  --from 'Acme <hello@yourdomain.com>' \
  --to 'delivered@example.com' \
  --subject 'Order confirmation' \
  --html '<p>Thanks for your order.</p>' \
  --headers '{"X-Entity-Ref-ID":"order_12345","X-Mailer-Campaign":"transactional"}'
```

## Header sanitization

Both header names and values are sanitized before they are written to the message: any carriage-return or line-feed characters (`\r`, `\n`) are stripped and collapsed to a single space. This prevents header injection — a value cannot smuggle in extra headers or a premature body break.

> **Note:** Don't set `List-Unsubscribe` by hand for transactional sends — for campaigns, MailBlastr injects the RFC 8058 `List-Unsubscribe` header automatically. See [Unsubscribe links](https://www.mailblastr.com/docs/emails/unsubscribe).