Save email tool connection¶

Saves the mail tool connection for the current workspace. The service tests the email connection first; the current connection credentials are not saved or rotated if the test fails. The password is only used for connection testing and saving and is not returned in the response.

POST https://moi.matrixorigin.cn/newmoi/workspaces/{workspace_id}/tools/mail/{provider}/connect

Before you call¶

Prepare a personal access token and target workspace ID that has access to the target workspace.

The example below uses:

$AI_STUDIO_API_KEY: The actual personal access token, passed through the X-API-Key Header.
$WORKSPACE_ID: The workspace ID to save the connection, passed through the X-Workspace-ID Header.

Request example¶

curl -X POST "https://moi.matrixorigin.cn/newmoi/workspaces/$WORKSPACE_ID/tools/mail/qq/connect" \
  -H "X-API-Key: $AI_STUDIO_API_KEY" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "user@example.com",
    "password": "<MAIL_PASSWORD>"
  }'

Path parameters¶

Parameters	Type	Is it required	Description
`workspace_id`	string	Yes	The current workspace ID.
`provider`	string	Yes	Email provider: `qq` or `wecom`.

Request body¶

Field	Type	Is it required	Description
`email`	string	Yes	Email address. It must be a complete and valid email address and cannot contain leading or trailing spaces.
`password`	string	Yes	Email password or authorization code. It cannot be empty and cannot contain leading or trailing blanks or newlines.

Successful response¶

Returns 200 on success. The return value does not contain the password.

{
  "code": 0,
  "data": {
    "tool_id": "moi.qq.mail",
    "provider": "qq",
    "email": "user@example.com",
    "credential_ref": "cred_01",
    "status": "connected",
    "connected_at": "2026-01-02T15:04:05Z",
    "requires_reconnect": false
  }
}

The response fields are as follows.

Field	Type	Description
`code`	integer	`0` on success.
`data.tool_id`	string	Corresponding provider’s built-in tool identifier.
`data.provider`	string	The connected mail provider.
`data.email`	string	Saved email address.
`data.credential_ref`	string	A reference to a saved credential, not a password.
`data.status`	string	Connection status and whether reconnection is required.
`data.requires_reconnect`	boolean	Connection status and whether reconnection is required.
`data.connected_at`	string	The time the connection was established, using RFC 3339 format.

Error response¶

{
  "code": 2,
  "message": "<错误信息>"
}

Common HTTP errors¶

HTTP status code	error code	Common causes	Recommended actions
`400`	`2`（`INVALID_ARGUMENT`）	`provider`, email, password or email connection test is invalid.	`provider` Use only `qq` or `wecom`; check email, password or authorization code.
`401`	`6`（`UNAUTHENTICATED`）	Lack of valid identity credentials.	Check API Key.
`403`	`5`（`PERMISSION_DENIED`）	The current identity does not have permission to manage tool connections in the workspace.	Check workspace authorization.
`404`	`3`（`NOT_FOUND`）	The corresponding built-in email tool cannot be found in the current environment.	Check the provider and confirm that the tool is available.
`503`	`15`（`UNAVAILABLE`）	The email connection service or authorization dependency is temporarily unavailable.	Try again later.

Follow-up operations¶

After saving, Query email tool connection confirms the connection configuration.

Last updated on Sep 3, 2026