Skip to main content

Using OpenAPI Development Skill

alimail-openapi-development This Skill is used to guide development agents such as Codex, Claude Code, and OpenClaw in designing, implementing, reviewing, and troubleshooting Alibaba Mail OpenAPI integrations. It covers application authentication, documentation lookup, security boundaries, and verification checklists, without duplicating complete interface documentation that quickly becomes outdated.

Applicable Scenarios​

  • Developing synchronization programs for organizations, domains, users, departments, mail groups, or shared contacts.
  • Developing features related to emails, attachments, calendars, quarantine, or audit logs.
  • Obtaining a Token using an App ID and Secret, and encapsulating the Alibaba Mail API client.
  • Querying interfaces, scopes, request fields, response structures, or error codes.
  • Troubleshooting issues such as 401, 403, 429, missing pagination, and incorrect server selection.

This Skill is intended for applications created by enterprise administrators in the API Open Platform. When using a personal MCP token to operate a single mailbox, please choose the Personal Access Skill instead. Do not mix these two types of credentials.

Skill Address​

https://mailhelp.aliyun.com/docs/skills/alimail-openapi-development/SKILL.md

Installing to Codex​

mkdir -p ~/.codex/skills/alimail-openapi-development/agents
curl -fsSL https://mailhelp.aliyun.com/docs/skills/alimail-openapi-development/SKILL.md \
  -o ~/.codex/skills/alimail-openapi-development/SKILL.md
curl -fsSL https://mailhelp.aliyun.com/docs/skills/alimail-openapi-development/agents/openai.yaml \
  -o ~/.codex/skills/alimail-openapi-development/agents/openai.yaml

After installation, create a new task or restart the current agent so that it rediscovers the Skill. Other development agents that support Skills can copy the same directory to their corresponding user-level Skill directory.

Invoking in a Task​

Use $alimail-openapi-development to add a client that retrieves every department page to the
existing Java service. Search the official docs for the endpoint, scope, and pagination fields
first, then follow the project's existing OkHttp style and add unit tests. Do not call a live
environment or introduce another HTTP framework.

The task description should clearly specify the target resource, runtime environment or region, technology stack, read/write actions, and whether access to the production environment is allowed.

Documentation Lookup​

The Skill first reads the agent entry point:

https://mailhelp.aliyun.com/docs/llms.txt

Then, it searches by capability name, API path, Operation ID, field name, or error code through the search interface:

curl --get 'https://mailhelp.aliyun.com/docs/agent/search' \
  --data-urlencode 'q=list all departments' \
  --data-urlencode 'locale=zh-CN' \
  --data-urlencode 'kind=api' \
  --data-urlencode 'limit=10'

The markdown_url in the search results points to the interface page suitable for agent reading. The agent should confirm the HTTP method, path, server, scope, parameters, response, pagination fields, and error codes from the specific page.

Common Examples​

The following Markdown pages can be directly provided to the agent. The URLs will resolve to the corresponding environment based on the current site:

Security Boundaries​

Installing the Skill does not authorize the agent to call production interfaces. Code changes do not automatically authorize sending emails, deleting or moving emails, batch modifying resources, releasing quarantined emails, or creating/deleting users and domains.

When integration testing is needed, clearly specify the target environment, organization or mailbox, interface actions, and resource scope. For operations with external impact or irreversible actions, require the agent to list the actions and targets before calling and confirm again.