# 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.

SendDart 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 { SendDart } from 'senddart';

const mb = new SendDart('mb_xxxxxxxxx');

const { data, error } = await mb.emails.send({
  "from": "Acme <hello@yourdomain.com>",
  "to": ["delivered@test.senddart.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 "senddart"

SendDart.api_key = "mb_xxxxxxxxx"

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

**PHP**

```php
<?php
require 'vendor/autoload.php';

use SendDart\SendDart;

$senddart = SendDart::client('mb_xxxxxxxxx');

$senddart->emails->send([
  'from' => "Acme <hello@yourdomain.com>",
  'to' => [
    "delivered@test.senddart.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 senddart

senddart.api_key = "mb_xxxxxxxxx"

senddart.Emails.send({
  "from": "Acme <hello@yourdomain.com>",
  "to": [
    "delivered@test.senddart.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/senddart-sdks/senddart-go"

client := senddart.NewClient("mb_xxxxxxxxx")

sent, err := client.Emails.Send(&senddart.SendEmailRequest{
    From:    "Acme <hello@yourdomain.com>",
    To:      []string{"delivered@test.senddart.com"},
    Subject: "Order confirmation",
    Html:    "<p>Thanks for your order.</p>",
    Headers: map[string]string{
        "X-Entity-Ref-ID":   "order_12345",
        "X-Mailer-Campaign": "transactional",
    },
})
```

**Rust**

```rust
use senddart::{SendDart, SendEmailOptions};

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

let params = SendEmailOptions::new(
    "Acme <hello@yourdomain.com>",
    ["delivered@test.senddart.com"],
    "Order confirmation",
)
.with_html("<p>Thanks for your order.</p>")
.with_header("X-Entity-Ref-ID", "order_12345")
.with_header("X-Mailer-Campaign", "transactional");
let _sent = mb.emails.send(params).await?;
```

**Java**

```java
import com.senddart.SendDart;
import com.senddart.SendDartResponse;
import com.senddart.requests.SendEmailRequest;

SendDart senddart = new SendDart("mb_xxxxxxxxx");

SendEmailRequest request = SendEmailRequest.builder()
        .from("Acme <hello@yourdomain.com>")
        .to("delivered@test.senddart.com")
        .subject("Order confirmation")
        .html("<p>Thanks for your order.</p>")
        .header("X-Entity-Ref-ID", "order_12345")
        .header("X-Mailer-Campaign", "transactional")
        .build();

SendDartResponse response = senddart.emails().send(request);
```

**.NET**

```csharp
using SendDart;

ISendDart senddart = SendDartClient.Create("mb_xxxxxxxxx");

var resp = await senddart.EmailSendAsync(new EmailMessage
{
    From = "Acme <hello@yourdomain.com>",
    To = "delivered@test.senddart.com",
    Subject = "Order confirmation",
    HtmlBody = "<p>Thanks for your order.</p>",
    Headers = new Dictionary<string, string>
    {
        ["X-Entity-Ref-ID"] = "order_12345",
        ["X-Mailer-Campaign"] = "transactional",
    },
});
```

**cURL**

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

**CLI**

```bash
senddart emails send \
  --from 'Acme <hello@yourdomain.com>' \
  --to 'delivered@test.senddart.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:** Set `List-Unsubscribe` by hand only on a transactional send (no `topic_id`), where SendDart adds nothing. For campaigns **and** for `POST /emails` sends that set `topic_id`, SendDart injects the RFC 8058 `List-Unsubscribe` header automatically — don't set it yourself there. See [Unsubscribe links](https://www.senddart.com/docs/emails/unsubscribe).