> ## Documentation Index
> Fetch the complete documentation index at: https://docs.emailr.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Headers

> Customize how emails are sent with your own headers.

Email headers are typically hidden from the end user but are crucial for deliverability. They include information about the sender, receiver, timestamp, and more.

Emailr already includes all the necessary headers for you, but now you can also add your own custom headers.

This is a fairly advanced feature, but it can be useful for a few things:

* Prevent threading on Gmail with the **`X-Entity-Ref-ID`** header ([Example](https://github.com/emailr/emailr-examples/tree/main/with-prevent-thread-on-gmail))
* Include a shortcut for users to unsubscribe with the **`List-Unsubscribe`** header ([Example](https://github.com/emailr/emailr-examples/tree/main/with-unsubscribe-url-header))

Here's how you can add custom headers to your emails:

<CodeGroup>
  ```ts Node.js {11} theme={null} theme={null}
  import { Emailr } from 'emailr';

  const emailr = new Emailr('em_xxxxxxxxx');

  await emailr.emails.send({
    from: 'Acme <onboarding@emailr.dev>',
    to: ['delivered@emailr.dev'],
    subject: 'hello world',
    html: '<p>it works!</p>',
    headers: {
      'X-Entity-Ref-ID': 'xxx_xxxx',
    },
  });
  ```

  ```php PHP {9} theme={null} theme={null}
  $emailr = Emailr::client('em_xxxxxxxxx');

  $emailr->emails->send([
    'from' => 'Acme <onboarding@emailr.dev>',
    'to' => ['delivered@emailr.dev'],
    'subject' => 'hello world',
    'html' => '<p>it works!</p>',
    'headers' => [
      'X-Entity-Ref-ID' => 'xxx_xxxx',
    ]
  ]);
  ```

  ```python Python {11} theme={null} theme={null}
  import emailr

  emailr.api_key = "em_xxxxxxxxx"

  params: emailr.Emails.SendParams = {
    "from": "onboarding@emailr.dev",
    "to": ["delivered@emailr.dev"],
    "subject": "hi",
    "html": "<p>it works!</p>",
    "headers": {
      "X-Entity-Ref-ID": "xxx_xxxx"
    }
  }

  email = emailr.Emails.send(params)
  print(email)
  ```

  ```rb Ruby {11} theme={null} theme={null}
  require "emailr"

  Emailr.api_key = "em_xxxxxxxxx"

  params = {
    "from": "Acme <onboarding@emailr.dev>",
    "to": ["delivered@emailr.dev"],
    "subject": "hello world",
    "html": "<p>it works!</p>",
    "headers": {
      "X-Entity-Ref-ID": "123"
    },
  }

  sent = Emailr::Emails.send(params)
  puts sent
  ```

  ```go Go {17} theme={null} theme={null}
  import (
  	"fmt"

  	"github.com/emailr/emailr-go/v3"
  )

  func main() {
    ctx := context.TODO()
    client := emailr.NewClient("em_xxxxxxxxx")

    params := &emailr.SendEmailRequest{
        From:        "Acme <onboarding@emailr.dev>",
        To:          []string{"delivered@emailr.dev"},
        Subject:     "hello world",
        Html:        "<p>it works!</p>",
        Headers:     map[string]string{
          "X-Entity-Ref-ID": "xxx_xxxx",
        }
    }

    sent, err := client.Emails.SendWithContext(ctx, params)

    if err != nil {
      panic(err)
    }
    fmt.Println(sent.Id)
  }
  ```

  ```rust Rust {14} theme={null} theme={null}
  use emailr_rs::types::{Attachment, CreateEmailBaseOptions, Tag};
  use emailr_rs::{Emailr, Result};

  #[tokio::main]
  async fn main() -> Result<()> {
    let emailr = Emailr::new("em_xxxxxxxxx");

    let from = "Acme <onboarding@emailr.dev>";
    let to = ["delivered@emailr.dev"];
    let subject = "hello world";

    let email = CreateEmailBaseOptions::new(from, to, subject)
      .with_html("<p>it works!</p>")
      .with_header("X-Entity-Ref-ID", "xxx_xxxx");

    let _email = emailr.emails.send(email).await?;

    Ok(())
  }
  ```

  ```java Java {13} theme={null} theme={null}
  import com.emailr.*;

  public class Main {
      public static void main(String[] args) {
          Emailr emailr = new Emailr("em_xxxxxxxxx");

          CreateEmailOptions params = CreateEmailOptions.builder()
                  .from("Acme <onboarding@emailr.dev>")
                  .to("delivered@emailr.dev")
                  .subject("hello world")
                  .html("<p>it works!</p>")
                  .headers(Map.of(
                      "X-Entity-Ref-ID", "xxx_xxxx"
                  ))
                  .build();

          CreateEmailResponse data = emailr.emails().send(params);
      }
  }
  ```

  ```csharp .NET {12-15} theme={null} theme={null}
  using Emailr;
  using System.Collections.Generic;

  IEmailr emailr = EmailrClient.Create( "em_xxxxxxxxx" ); // Or from DI

  var message = new EmailMessage()
  {
      From = "Acme <onboarding@emailr.dev>",
      To = "delivered@emailr.dev",
      Subject = "hello world",
      HtmlBody = "<p>it works!</p>",
      Headers = new Dictionary<string, string>()
      {
          { "X-Entity-Ref-ID", "xxx_xxxx" },
      },
  };

  var resp = await emailr.EmailSendAsync( message );
  Console.WriteLine( "Email Id={0}", resp.Content );
  ```

  ```bash cURL {10} theme={null} theme={null}
  curl -X POST 'https://api.emailr.dev/emails' \
       -H 'Authorization: Bearer em_xxxxxxxxx' \
       -H 'Content-Type: application/json' \
       -d $'{
    "from": "Acme <onboarding@emailr.dev>",
    "to": ["delivered@emailr.dev"],
    "subject": "hello world",
    "html": "<p>it works!</p>",
    "headers": {
      "X-Entity-Ref-ID": "xxx_xxxx"
    }
  }'
  ```
</CodeGroup>