Skip to main content

Alibaba Mail API Open Platform

Alibaba Mail API Open Platform lets enterprise systems and automation scripts use Alibaba Mail capabilities through documented APIs. It covers organizations, domains, users, departments, mail groups, shared contacts, mail, calendars, login, audit logs, file streams, quarantine, and rules. Typical use cases include account lifecycle management, organization sync, mail and calendar automation, security audits, quarantine handling, internal admin tools, and batch scripts.

The Free Edition of Alibaba Mail does not support the API Open Platform. Before using the APIs, an enterprise administrator must create an application in the admin console, grant API permissions, and protect the application credentials.

Integration Model​

  1. In the admin console, open Advanced Applications or API Open Platform and create an application.
  2. Grant the minimum required scopes, such as User.ReadWrite.All, Department.Read.All, Mail.Read.All, Mail.Send.All, and Calendar.ReadWrite.All.
  3. Obtain the application's client_id and client_secret, then exchange them for an access token through the OAuth2 client credentials flow.
  4. Send business API requests with the Authorization: Bearer <access_token> header.
  5. Use the Base URL shown on the API page for the enterprise region and current environment: https://alimail-cn.aliyuncs.com. Never reuse an address across clusters.

Get Access Credentials​

Obtain an Authorization Token​

Before calling Alibaba Mail APIs, create an application in API Open Platform in the Alibaba Mail admin console and grant it the required permissions. Then use the application's client_id and client_secret to call the authorization endpoint and obtain an authorization token. The request is as follows:

POST /oauth2/v2.0/token HTTP/1.1
Host: alimail-cn.aliyuncs.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>

Request parameters:

ParameterRequiredDescription
grant_typeYFixed value: client_credentials.
client_idYThe application ID used to request an authorization token. The enterprise administrator obtains it after registering the application in the admin console.
client_secretYThe application secret used to request an authorization token. The enterprise administrator obtains it after registering the application in the admin console. Do not disclose it: anyone with the application ID and secret can call APIs as that application.

Response parameters:

ParameterDescription
token_typeToken type. Currently always bearer.
access_tokenAuthorization token.
expires_inAuthorization token lifetime in seconds. Cache the token and request a new one after it expires.

Request example (curl):

curl -X POST \
  'https://alimail-cn.aliyuncs.com/oauth2/v2.0/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>'

Request example (Java, using OkHttpClient):

OkHttpClient client = new OkHttpClient();
MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(
    mediaType,
    "grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>"
);
Request request = new Request.Builder()
    .url("https://alimail-cn.aliyuncs.com/oauth2/v2.0/token")
    .post(body)
    .addHeader("Content-Type", "application/x-www-form-urlencoded")
    .build();
Response response = client.newCall(request).execute();

Response example:

{
  "token_type": "bearer",
  "access_token": "...",
  "expires_in": 172799
}

Pass the Authorization Token to API Calls​

Every Open API call must include a valid authorization token in the HTTP Authorization request header. Prefix the token value with Bearer.

Request example:

curl -X POST \
  'https://alimail-cn.aliyuncs.com/...' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <access_token>' \
  ...

API Traffic Limits​

The aggregate API traffic of all applications in a single domain must not exceed 40 requests per second. Requests over the limit return HTTP status 429.

Core Concepts​

ConceptDefinition
OrganizationThe top-level enterprise mailbox tenant. It contains domains, users, departments, mail groups, shared contacts, and other resources.
DomainThe domain used for enterprise mail sending and receiving. Domain APIs create, query, verify, and manage enterprise domains.
UserA mailbox account. User APIs cover account creation, profile updates, password reset, aliases, security phone numbers, mailbox settings, and shared members.
DepartmentA node in the enterprise organization tree. Department sync usually starts from the root department and recursively reads sub-departments and members.
Mail GroupA group address and its member set, used for unified receiving, distribution, and access control.
Shared ContactA contact or contact folder in the enterprise shared address book, separate from personal contacts.
MailMail folders, message lists, message details, attachments, drafts, sending, moving, deleting, and batch updates.
CalendarCalendars, events, sharing, import/export, and meeting replies.
QuarantineA temporary container between the inbox and spam/trash flows. It stores messages intercepted by anti-spam, anti-virus, or anti-phishing rules. Quarantined messages are typically retained for 30 days.
File StreamUpload, download, chunking, or redirect capabilities for attachments and large files.
ScopeThe permission range granted to an application. Each API page lists required scopes. Request the exact scopes needed by the API instead of granting broad permissions by default.
CursorA cursor-based pagination marker. List APIs often return the next cursor, and callers must continue reading until no next page is available.

Capability Map​

  • Organization and domains: read organization information, update organization settings, create, query, verify, and delete domains.
  • Users and departments: create accounts, update account profiles, reset passwords, manage aliases, security phone numbers, mailbox settings and shared relationships, and recursively sync department trees and members.
  • Mail groups and shared contacts: manage mail groups, members, shared contacts, and shared contact folders.
  • Mail: list mail folders and messages, read message details, create drafts, upload attachments, send drafts, move, copy, delete, and batch-update messages.
  • Calendar: manage calendars, events, shared calendars, event import/export, and meeting invitation replies.
  • Security and governance: query audit logs, process quarantined messages, and maintain inbound allow/block lists and related rules.
  • Login and file streams: generate passwordless login links, invalidate login tokens, and handle attachment upload/download and file streams.

Common Workflows​

Create Accounts and Sync the Organization Tree​

  1. Query or create departments and store department IDs.
  2. Call the user creation API with the mailbox address, name, department, password policy, and related fields.
  3. If aliases, security phone numbers, or mailbox settings are required, call the corresponding user extension APIs.
  4. For batch sync, process data by department tree batches so organization structure writes and account writes are not mixed out of order.

Read the Complete Department Tree​

  1. Get the root department ID. Some APIs allow $root to represent the root department.
  2. Call the API that lists sub-departments.
  3. Recursively read each sub-department until no child nodes remain.
  4. If an API returns pagination fields, continue reading with the cursor or pagination parameters from the response.

Read Messages and Attachments​

  1. Select the user mailbox and mail folder.
  2. Call the message list API and page by cursor, size, sorting fields, and time range.
  3. Call the message detail API to read the body, sender, recipients, and metadata.
  4. Call the attachment list API to get attachment IDs.
  5. Create an attachment download session, then read the attachment from the returned URL or file stream.

Create a Draft and Send Mail​

The Alibaba Mail API sending flow usually creates a draft first and then sends the draft. This capability is intended for special scenarios tightly coupled to a user's mailbox. For large-scale system notifications, marketing mail, or bulk outbound mail, use a dedicated product such as Alibaba Cloud DirectMail/Mail Push.

  1. Create a draft with recipients, subject, body, and attachment information.
  2. If attachments are required, create an upload session and upload the files first.
  3. Call the send draft API.
  4. Confirm the result from the response and audit logs.

Process Quarantined Messages​

Quarantine stores messages intercepted by security policies. Common actions include searching quarantined messages, reading message details, listing attachments, releasing messages to the inbox, deleting messages, and maintaining allow/block lists. Blocklist hits are usually deleted directly, while allowlist hits are usually delivered directly. Confirm scope and rule priority before changing rules.

Request and Response Conventions​

  • JSON request bodies and JSON responses are used by default, except for file stream APIs.
  • Path parameters, query parameters, and body parameters are defined on each API page.
  • Every business API requires Authorization: Bearer <access_token>.
  • 401 usually means the token is missing, invalid, or expired.
  • 403 usually means the application does not have permission for the API. Grant the required permission in the admin console.
  • 429 means that the request was rate limited. The aggregate API traffic of all applications in a single domain must not exceed 40 requests per second.
  • 400, 404, 409, and similar errors usually include detailErrorCode and message. Scripts should read these fields instead of only checking the HTTP status.
  • List APIs often include cursor, nextCursor, hasMore, and size. Do not read only the first page.

Security Guidance​

  • Use least-privilege scopes and split permissions by application responsibility.
  • Do not log client_secret, access tokens, user passwords, or attachment download URLs.
  • Cache tokens until shortly before expiration and refresh them when needed. Do not request a new token for every business API call.
  • Production scripts need retry, rate-limit handling, idempotency, and audit records.
  • Add human confirmation or a small rollout scope for high-risk actions such as delete, batch update, releasing quarantined messages, or sending mail.

Official References​