All Products
Document Center

Direct Mail:Java SDK manual

Last Updated:Aug 23, 2023

This topic describes how to install and use the Java SDK.

Create an Access Key

(Note: You can also use the Access Key created by Alibaba Cloud RAM Service.)

  1. Log on to the Access Key Management console.

  2. Click Create Access Key in the upper-right corner of the page. The Create Access Key dialog box appears.

  3. Read the API usage specifications and click Agree and Create.

Install the Java SDK

Development Environment

Alibaba Cloud Java SDK supports J2 SE Development Kit (JDK) 1.6 or later.

(Recommend)Install the SDK

Install through Maven

1. Add the Maven library.

You can obtain the new version number on the OpenAPI page and "SDK dependency information".


2. Jump to openAPI for debugging, select the development language, enter parameters, and download the automatically generated code (the parameter value will be included).

You do not need to enter the Key value on the debugging page.


Do not hard coding the "accessKeyId" and "accessKeySecret" values in the code to avoid disclosure.

  • The Alibaba Cloud SDK supports defining defining the values of ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET in the environment variables of the operating system, after obtaining the values from the environment variables in the code, authentication can be performed.


OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.


(Not recommend)The installation method of the old SDK.

SDK download

Install the SDK

Manual installation

  1. You can find the aliyun-java-sdk-dm-3.1.0.jar and aliyun-java-sdk-core-3.0.0.jar packages in the decompressed file.

  2. Take Eclipse to import a JAR package as an example: Right-click the Project on Eclipse, and then click Properties > Java Build Path > Libraries > Add External JARs. For other idea users such as netbeans and intellij, please import the JAR package according to the corresponding method.

  3. Select the preceding JAR package and click OK.

After the above steps, you can use Aliyun Java SDK in the project.

Install through Maven

  1. Add a Maven library

                 <name>Sonatype Nexus Staging</name>
  2. Add a JAR package


Example of sending email

For an example of how to call a single sender API, see the SingleSendMail:

import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.http.MethodType;
import com.aliyuncs.profile.DefaultProfile;
import com.aliyuncs.profile.IClientProfile;

public class Sample {

    public void singleSendMail() {
        //If you are not in the China (Hangzhou) region, replace cn-hangzhou in the following code with your region ID. For example, if you are in the Singapore (Singapore) or Australia (Sydney) region, specify ap-southeast-1 or ap-southeast-2. 
        //Please configure in the environment variables ALIBABA_CLOUD_ACCESS_KEY_ID,ALIBABA_CLOUD_ACCESS_KEY_SECRET.
        //Reference documents:  
        IClientProfile profile = DefaultProfile.getProfile("cn-hangzhou", System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        //If you are in a region other than China (Hangzhou), perform the following operation:
        //try {
        //DefaultProfile.addEndpoint("", "ap-southeast-1", "Dm",  "");
        //} catch (ClientException e) {
        IAcsClient client = new DefaultAcsClient(profile);
        SingleSendMailRequest request = new SingleSendMailRequest();
        try {
            // request.setVersion("2017-06-22");// If it is a region other than the Hangzhou region, such as the Singapore region, it must be set to 2017-06-22.
            request.setAccountName("The sender address created in the console");
            request.setFromAlias("The sender's nickname");// The sender's nickname. The name must be less than 15 characters in length. 
            request.setAddressType(1);//0: is a random account 1: is a sender address.
            request.setTagName("The tag created in the console");
            request.setReplyToAddress(true);// Specifies whether to enable the return address configured in the management console (the status must be verified). The value range is true or false.
            request.setToAddress("Destination address");
            // You can send emails to multiple recipients. The recipients are separated by commas. BatchSendMailRequest method is recommended for batch sending.
            // request.setToAddress("Email 1, Email 2");
            request.setSubject("Email subject");
            // If the byte[].toString method is used, make sure that it is finally converted into the utf-8 format and then put into the htmlbody and textbody. If the encoding is inconsistent, it will be regarded as spam. 
            // Note: The size of text mail is limited to 3M. Excessive text will cause connection timeout or 413 errors
            request.setHtmlBody("Email body");
            // The SDK uses the HTTP protocol to send messages. The default is the GET method, which has a certain length limit. 
            // If the size of the textBody, htmlBody, or content is uncertain, we recommend that you submit it in POST mode to avoid uri is not valid exceptions.
            // Enable ICP filing, 0 disable, 1 enable
            // If the call is successful, httpResponse is returned. If the call fails, an exception is thrown. You must catch the error code in the exception. For more information about the error code, see the API documentation.
            SingleSendMailResponse httpResponse = client.getAcsResponse(request);
        } catch (ServerException e) {
            // Capture the error exception code.
            System.out.println("ErrCode : " + e.getErrCode());
        catch (ClientException e) {
            // Capture the error exception code.
            System.out.println("ErrCode : " + e.getErrCode());

Click here for more tips about how to use the SDK for Java.

Also call the template batch to send letters, please use the BatchSendMailRequest, related modifications:

request.setTemplateName("test template");

Where "test template" is the template name; "test-test" is the name of the recipient list.