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

# Managing Tags

> Add unique identifiers to emails sent.

Tags are unique identifiers you can add to your emails. They help associate emails with your application. They are passed in key/value pairs. After the email is sent, the tag is included in the webhook event. Tags can include ASCII letters, numbers, underscores, or dashes.

Some examples of when to use a tag:

* Associate the email a "customer ID" from your application
* Add a label from your database like "free" or "enterprise"
* Note the category of email sent, like "welcome" or "password reset"

Here's how you can add custom tags to your emails.

## Add tags on the `POST /emails` endpoint

<CodeGroup>
  ```ts Node.js {10-15} 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>',
    tags: [
      {
        name: 'category',
        value: 'confirm_email',
      },
    ],
  });
  ```

  ```php PHP {8-13} 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>',
    'tags' => [
      [
        'name' => 'category',
        'value' => 'confirm_email',
      ],
    ]
  ]);
  ```

  ```python Python {10-12} theme={null} theme={null}
  import emailr

  emailr.api_key = "em_xxxxxxxxx"

  params: emailr.Emails.SendParams = {
    "from": "Acme <onboarding@emailr.dev>",
    "to": ["delivered@emailr.dev"],
    "subject": "hello world",
    "html": "<p>it works!</p>",
    "tags": [
      {"name": "category", "value": "confirm_email"},
    ],
  }

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

  ```rb Ruby {10-12} 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>",
    "tags": [
      {"name": "category", "value": "confirm_email"}
    ]
  }

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

  ```go Go {16} 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"},
        Text:        "<p>it works!</p>",
        Subject:     "hello world",
        Tags:        []emailr.Tag{{Name: "category", Value: "confirm_email"}},
    }

    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::{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_tag(Tag::new("category", "confirm_email"));

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

    Ok(())
  }
  ```

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

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

          Tag tag = Tag.builder()
                  .name("category")
                  .value("confirm_email")
                  .build();

          SendEmailRequest sendEmailRequest = SendEmailRequest.builder()
                  .from("Acme <onboarding@emailr.dev>")
                  .to("delivered@emailr.dev")
                  .subject("hello world")
                  .html("<p>it works!</p>")
                  .tags(tag)
                  .build();

          SendEmailResponse data = emailr.emails().send(sendEmailRequest);
      }
  }
  ```

  ```csharp .NET {12} theme={null} theme={null}
  using Emailr;

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

  var resp = await emailr.EmailSendAsync( new EmailMessage()
  {
      From = "Acme <onboarding@emailr.dev>",
      To = "delivered@emailr.dev",
      Subject = "hello world",
      HtmlBody = "<p>it works!</p>",
      ReplyTo = "onboarding@emailr.dev",
      Tags = new List<EmailTag> { new EmailTag { Name = "category", Value = "confirm_email" } }
  } );
  Console.WriteLine( "Email Id={0}", resp.Content );
  ```

  ```bash cURL {9-14} 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>",
    "tags": [
      {
        "name": "category",
        "value": "confirm_email"
      }
    ]
  }'
  ```
</CodeGroup>

## Add tags on the `POST /emails/batch` endpoint

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

  const emailr = new Emailr('em_xxxxxxxxx');

  const { data, error } = await emailr.batch.send([
    {
      from: 'Acme <onboarding@emailr.dev>',
      to: ['foo@gmail.com'],
      subject: 'hello world',
      html: '<h1>it works!</h1>',
      tags: [
        {
          name: 'category',
          value: 'confirm_email',
        },
      ],
    },
    {
      from: 'Acme <onboarding@emailr.dev>',
      to: ['bar@outlook.com'],
      subject: 'world hello',
      html: '<p>it works!</p>',
      tags: [
        {
          name: 'category',
          value: 'confirm_email',
        },
      ],
    },
  ]);
  ```

  ```php PHP {9-13,21-25} theme={null} theme={null}
  $emailr = Emailr::client('em_xxxxxxxxx');

  $emailr->batch->send([
    [
      'from' => 'Acme <onboarding@emailr.dev>',
      'to' => ['foo@gmail.com'],
      'subject' => 'hello world',
      'html' => '<h1>it works!</h1>',
      'tags' => [
        [
          'name' => 'category',
          'value' => 'confirm_email'
        ]
      ]
    ],
    [
      'from' => 'Acme <onboarding@emailr.dev>',
      'to' => ['bar@outlook.com'],
      'subject' => 'world hello',
      'html' => '<p>it works!</p>',
      'tags' => [
        [
          'name' => 'category',
          'value' => 'confirm_email'
        ]
      ]
    ]
  ]);
  ```

  ```py Python {12-17,24-29} theme={null} theme={null}
  import emailr
  from typing import List

  emailr.api_key = "em_xxxxxxxxx"

  params: List[emailr.Emails.SendParams] = [
    {
      "from": "Acme <onboarding@emailr.dev>",
      "to": ["foo@gmail.com"],
      "subject": "hello world",
      "html": "<h1>it works!</h1>",
      "tags": [
        {
          "name": "category",
          "value": "confirm_email"
        }
      ]
    },
    {
      "from": "Acme <onboarding@emailr.dev>",
      "to": ["bar@outlook.com"],
      "subject": "world hello",
      "html": "<p>it works!</p>",
      "tags": [
        {
          "name": "category",
          "value": "confirm_email"
        }
      ]
    }
  ]

  emailr.Batch.send(params)
  ```

  ```rb Ruby {11-16,23-28} theme={null} theme={null}
  require "emailr"

  Emailr.api_key = 'em_xxxxxxxxx'

  params = [
    {
      "from": "Acme <onboarding@emailr.dev>",
      "to": ["foo@gmail.com"],
      "subject": "hello world",
      "html": "<h1>it works!</h1>",
      "tags": [
        {
          "name": "category",
          "value": "confirm_email"
        }
      ]
    },
    {
      "from": "Acme <onboarding@emailr.dev>",
      "to": ["bar@outlook.com"],
      "subject": "world hello",
      "html": "<p>it works!</p>",
      "tags": [
        {
          "name": "category",
          "value": "confirm_email"
        }
      ]
    }
  ]

  Emailr::Batch.send(params)
  ```

  ```go Go {22,29} theme={null} theme={null}
  package examples

  import (
  	"fmt"
  	"os"

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

  func main() {

    ctx := context.TODO()

    client := emailr.NewClient("em_xxxxxxxxx")

    var batchEmails = []*emailr.SendEmailRequest{
      {
        From:    "Acme <onboarding@emailr.dev>",
        To:      []string{"foo@gmail.com"},
        Subject: "hello world",
        Html:    "<h1>it works!</h1>",
        Tags:    []emailr.Tag{{Name: "category", Value: "confirm_email"}},
      },
      {
        From:    "Acme <onboarding@emailr.dev>",
        To:      []string{"bar@outlook.com"},
        Subject: "world hello",
        Html:    "<p>it works!</p>",
        Tags:    []emailr.Tag{{Name: "category", Value: "confirm_email"}},
      },
    }

    sent, err := client.Batch.SendWithContext(ctx, batchEmails)

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

  ```rust Rust {15,22} theme={null} theme={null}
  use emailr_rs::types::CreateEmailBaseOptions;
  use emailr_rs::{Emailr, Result};

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

    let emails = vec![
      CreateEmailBaseOptions::new(
        "Acme <onboarding@emailr.dev>",
        vec!["foo@gmail.com"],
        "hello world",
      )
      .with_html("<h1>it works!</h1>")
      .with_tag(Tag::new("category", "confirm_email")),
      CreateEmailBaseOptions::new(
        "Acme <onboarding@emailr.dev>",
        vec!["bar@outlook.com"],
        "world hello",
      )
      .with_html("<p>it works!</p>")
      .with_tag(Tag::new("category", "confirm_email")),
    ];

    let _emails = emailr.batch.send(emails).await?;

    Ok(())
  }
  ```

  ```java Java {12-15,23-26} theme={null} theme={null}
  import com.emailr.*;

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

          CreateEmailOptions firstEmail = CreateEmailOptions.builder()
              .from("Acme <onboarding@emailr.dev>")
              .to("foo@gmail.com")
              .subject("hello world")
              .html("<h1>it works!</h1>")
              .tags(Tag.builder()
                  .name("category")
                  .value("confirm_email")
                  .build())
              .build();

          CreateEmailOptions secondEmail = CreateEmailOptions.builder()
              .from("Acme <onboarding@emailr.dev>")
              .to("bar@outlook.com")
              .subject("world hello")
              .html("<p>it works!</p>")
              .tags(Tag.builder()
                  .name("category")
                  .value("confirm_email")
                  .build())
              .build();

          CreateBatchEmailsResponse data = emailr.batch().send(
              Arrays.asList(firstEmail, secondEmail)
          );
      }
  }
  ```

  ```csharp .NET {11,20} theme={null} theme={null}
  using Emailr;

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

  var mail1 = new EmailMessage()
  {
      From = "Acme <onboarding@emailr.dev>",
      To = "foo@gmail.com",
      Subject = "hello world",
      HtmlBody = "<p>it works!</p>",
      Tags = new List<EmailTag> { new EmailTag { Name = "category", Value = "confirm_email" } }
  };

  var mail2 = new EmailMessage()
  {
      From = "Acme <onboarding@emailr.dev>",
      To = "bar@outlook.com",
      Subject = "hello world",
      HtmlBody = "<p>it works!</p>",
      Tags = new List<EmailTag> { new EmailTag { Name = "category", Value = "confirm_email" } }
  };

  var resp = await emailr.EmailBatchAsync( [ mail1, mail2 ] );
  Console.WriteLine( "Nr Emails={0}", resp.Content.Count );
  ```

  ```bash cURL {10-15,22-27} theme={null} theme={null}
  curl -X POST 'https://api.emailr.dev/emails/batch' \
       -H 'Authorization: Bearer em_xxxxxxxxx' \
       -H 'Content-Type: application/json' \
       -d $'[
    {
      "from": "Acme <onboarding@emailr.dev>",
      "to": ["foo@gmail.com"],
      "subject": "hello world",
      "html": "<h1>it works!</h1>",
      "tags": [
        {
          "name": "category",
          "value": "confirm_email"
        }
      ]
    },
    {
      "from": "Acme <onboarding@emailr.dev>",
      "to": ["bar@outlook.com"],
      "subject": "world hello",
      "html": "<p>it works!</p>",
      "tags": [
        {
          "name": "category",
          "value": "confirm_email"
        }
      ]
    }
  ]'
  ```
</CodeGroup>