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:

<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:

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.

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

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