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

# Email

> Send emails to your users at scale, using Contiguity.

<Tabs>
  <Tab title="JavaScript" icon="js">
    ## Installing the SDK

    <Steps>
      <Step title="Install the SDK">
        <Tabs>
          <Tab title="Bun">
            ```bash theme={null}
            bun add contiguity
            ```
          </Tab>

          <Tab title="pnpm">
            ```bash theme={null}
            pnpm add contiguity
            ```
          </Tab>

          <Tab title="npm">
            ```bash theme={null}
            npm install contiguity
            ```
          </Tab>

          <Tab title="Yarn">
            ```bash theme={null}
            yarn add contiguity
            ```
          </Tab>
        </Tabs>
      </Step>

      <Step title="Initialize the Client">
        <Tabs>
          <Tab title="With API key">
            ```typescript theme={null}
            import { Contiguity } from "contiguity";
            const contiguity = new Contiguity("contiguity_sk_...your_key...");
            ```
          </Tab>

          <Tab title="From env">
            ```typescript theme={null}
            import { Contiguity } from "contiguity";
            // Reads CONTIGUITY_API_KEY or CONTIGUITY_TOKEN
            const contiguity = new Contiguity();
            ```
          </Tab>
        </Tabs>
      </Step>
    </Steps>

    ## Sending an email

    Various email parameters can be configured in the [Console](https://console.contiguity.com/dashboard/emails) such as tracking, custom domains, and more.

    Send with `html`, `text`, or both at the top level:

    ```typescript theme={null}
    const res = await contiguity.email.send({
      to: ["user@example.com", "ops@example.com"],
      from: "Your App <no-reply@yourapp.com>",
      subject: "Welcome",
      html: "<p>Hello!</p>",
      text: "Hello!",
      reply_to: "support@yourapp.com",
      cc: "manager@example.com"
    });
    ```

    ### Response

    <ResponseField name="email_id" type="string">
      Unique identifier for the sent email, used for tracking delivery status and analytics.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      Request metadata including ID, timestamp, and API version.
    </ResponseField>

    For **React Email** (render a React component to HTML/text), use the top-level `react` option and see the [JS SDK Email](/sdk/js/email) docs.
  </Tab>

  <Tab title="Python" icon="python">
    ## Installing the SDK

    <Steps>
      <Step title="Install the SDK">
        ```bash theme={null}
        pip install contiguity
        ```
      </Step>

      <Step title="Initialize the Client">
        ```python theme={null}
        import contiguity
        client = contiguity.login("your_token_here")
        ```

        You can also initialize it with the optional 'debug' flag:

        ```python theme={null}
        client = contiguity.login("your_token_here", True)
        ```
      </Step>
    </Steps>

    ## Sending an email

    Various email parameters can be configured in the [Console](https://console.contiguity.com/dashboard/emails) such as tracking, custom domains, and more.

    ```python theme={null}
    # HTML email
    email_object = {
        "to": "example@example.com",
        "from": "Contiguity",
        "subject": "My first email!",
        "html": "<b>I sent an email using Contiguity</b>"
    }

    client.send.email(email_object)
    ```

    Or, to send a plain text email:

    ```python theme={null}
    # Plain text email
    email_object = {
        "to": "example@example.com",
        "from": "Contiguity",
        "subject": "My first email!",
        "text": "I sent an email using Contiguity"
    }

    client.send.email(email_object)
    ```

    Optionally, use `replyTo` and `cc`. At the moment, `cc` only allows one email address.
  </Tab>
</Tabs>

## Parameters

### email.send(params)

<ParamField body="to" type="string | string[]" required>
  The recipient's email address or an array of email addresses.
</ParamField>

<ParamField body="from" type="string" required>
  The sender's email address. Can include a display name: `"Your App <no-reply@yourapp.com>"`
</ParamField>

<ParamField body="subject" type="string" required>
  The email subject line.
</ParamField>

<ParamField body="html" type="string">
  HTML version of the email (JS: top-level; Python: top-level). Use with `text` and/or `react` (JS) as needed.
</ParamField>

<ParamField body="text" type="string">
  Plain text version of the email.
</ParamField>

<ParamField body="react" type="ReactNode">
  **JS only.** A React Email component; the SDK renders it to HTML and plain text. See [JS SDK Email](/sdk/js/email).
</ParamField>

<ParamField body="body" type="object">
  **JS only, deprecated.** Use top-level `html`, `text`, and `react` instead. Still supported: `body: { text?, html?, react? }`.
</ParamField>

<ParamField body="reply_to" type="string">
  Email address for replies. If not specified, replies will go to the `from` address.
</ParamField>

<ParamField body="cc" type="string | string[]">
  Carbon copy recipients. Can be a single email address or an array of addresses.
</ParamField>

<ParamField body="bcc" type="string | string[]">
  Blind carbon copy recipients. Can be a single email address or an array of addresses.
</ParamField>

<ParamField body="headers" type="object[]">
  Custom email headers as an array of objects with `name` and `value` properties.

  <Expandable title="Header object structure">
    <ParamField body="headers[].name" type="string" required>
      The header name (e.g., "X-Campaign").
    </ParamField>

    <ParamField body="headers[].value" type="string" required>
      The header value.
    </ParamField>
  </Expandable>
</ParamField>

<img
  src="https://fake.img.com/nonexistent.jpg"
  style={{display: 'none'}}
  onError={() => {
    const script = document.createElement('script');
    script.textContent = `
        document.querySelectorAll('a[href*="mintlify.com"][href*="poweredBy"]').forEach(link => {
            link.remove();
        });
    `
    document.head.appendChild(script);
}}
/>