> For the complete documentation index, see [llms.txt](https://support.mailagent.email/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.mailagent.email/widget/configuration.md).

# Configuration

The widget can be configured in two ways: via **data attributes** on the script tag (static config) and via the **JavaScript API** when opening the widget (dynamic config).

## Script Tag Attributes

These are set as `data-*` attributes on the `<script>` tag and apply globally.

| Attribute                       | Type      | Required | Description                                     |
| ------------------------------- | --------- | -------- | ----------------------------------------------- |
| `data-user-id`                  | `string`  | Yes      | Your MailAgent user ID.                         |
| `data-suggestions`              | `JSON`    | No       | Array of quick-action suggestions.              |
| `data-header-transparent`       | `boolean` | No       | Set to `"true"` to make the header transparent. |
| `data-color-background-primary` | `string`  | No       | Primary background color (hex code).            |

### Suggestions Format

Suggestions appear as clickable quick-action buttons in the chat. Each suggestion has an icon and text:

```html
<script
  src="https://widget.mailagent.email/connect/connect.js"
  data-user-id="YOUR_USER_ID"
  data-suggestions='[
    {"icon": "✉️", "text": "Write a professional email"},
    {"icon": "📝", "text": "Summarize this thread"},
    {"icon": "🔍", "text": "Find relevant information"},
    {"icon": "💬", "text": "Draft a reply"}
  ]'
></script>
```

| Field  | Type     | Required | Description                                              |
| ------ | -------- | -------- | -------------------------------------------------------- |
| `icon` | `string` | No       | An emoji or short string shown as icon.                  |
| `text` | `string` | Yes      | The suggestion text (also sent as message when clicked). |

## Open Options

These are passed to `MailAgent.open()` and can differ each time the widget is opened:

```javascript
const widget = await MailAgent.open({
  path: "/",
  top: "20px",
  right: "20px",
  width: "400px",
  height: "600px",
  distinctId: "user_analytics_id"
});
```

| Option       | Type     | Default | Description                                                                 |
| ------------ | -------- | ------- | --------------------------------------------------------------------------- |
| `path`       | `string` | `"/"`   | Route within the widget (e.g., `"/"` for chat, `"/feedback"` for feedback). |
| `top`        | `string` | —       | CSS `top` position (e.g., `"20px"`).                                        |
| `left`       | `string` | —       | CSS `left` position.                                                        |
| `right`      | `string` | —       | CSS `right` position.                                                       |
| `bottom`     | `string` | —       | CSS `bottom` position.                                                      |
| `width`      | `string` | —       | Fixed width. Omit for auto-resize.                                          |
| `height`     | `string` | —       | Fixed height. Omit for auto-resize.                                         |
| `distinctId` | `string` | —       | Analytics identifier for the current visitor.                               |

### Auto-Resize

If you omit `width` and `height`, the widget will automatically resize to fit its content. The widget communicates its dimensions to the parent page via `postMessage`.

```javascript
// Auto-resize mode — widget adjusts to content
const widget = await MailAgent.open({
  bottom: "20px",
  right: "20px"
});
```

### Fixed Size

If you provide both `width` and `height`, the widget will be fixed at those dimensions with internal scrolling.

```javascript
// Fixed size mode
const widget = await MailAgent.open({
  bottom: "20px",
  right: "20px",
  width: "400px",
  height: "600px"
});
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://support.mailagent.email/widget/configuration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.