All Products
Search
Document Center

Direct Mail:SingleSendMail

Last Updated:Dec 23, 2025

Sends a single email.

Try it now

Try this API in OpenAPI Explorer, no manual signing needed. Successful calls auto-generate SDK code matching your parameters. Download it with built-in credential security for local usage.

Test

RAM authorization

The table below describes the authorization required to call this API. You can define it in a Resource Access Management (RAM) policy. The table's columns are detailed below:

  • Action: The actions can be used in the Action element of RAM permission policy statements to grant permissions to perform the operation.

  • API: The API that you can call to perform the action.

  • Access level: The predefined level of access granted for each API. Valid values: create, list, get, update, and delete.

  • Resource type: The type of the resource that supports authorization to perform the action. It indicates if the action supports resource-level permission. The specified resource must be compatible with the action. Otherwise, the policy will be ineffective.

    • For APIs with resource-level permissions, required resource types are marked with an asterisk (*). Specify the corresponding Alibaba Cloud Resource Name (ARN) in the Resource element of the policy.

    • For APIs without resource-level permissions, it is shown as All Resources. Use an asterisk (*) in the Resource element of the policy.

  • Condition key: The condition keys defined by the service. The key allows for granular control, applying to either actions alone or actions associated with specific resources. In addition to service-specific condition keys, Alibaba Cloud provides a set of common condition keys applicable across all RAM-supported services.

  • Dependent action: The dependent actions required to run the action. To complete the action, the RAM user or the RAM role must have the permissions to perform all dependent actions.

Action

Access level

Resource type

Condition key

Dependent action

dm:SingleSendMail

none

*All Resource

*

None None

Request parameters

Parameter

Type

Required

Description

Example

AccountName

string

Yes

The sender address configured in the Direct Mail console.

test***@example.net

AddressType

integer

Yes

The type of the address. Valid values:

0: A random account

1: A sender address

1

TagName

string

No

The tag created in the Direct Mail console. Use tags to classify email batches and query the sending status of each batch. If email tracking is enabled, you must specify an email tag. The tag can be 1 to 128 characters in length and can contain letters, digits, underscores (_), and hyphens (-).

test

ReplyToAddress

boolean

Yes

Specifies whether to use the reply-to address configured in the console. The reply-to address must be verified. Valid values: true and false.

true

ToAddress

string

Yes

The destination address. To specify multiple addresses, separate them with commas (,). You can specify a maximum of 100 addresses. Recipient groups are supported.

test1***@example.net

Subject

string

Yes

The subject of the email. The subject cannot exceed 256 characters in length.

Subject

HtmlBody

string

No

The HTML body of the email.

Note: Specify HtmlBody or TextBody.

  • The size of the parameter passed in a URL is limited to about 80 KB.

  • The size of the parameter passed in the body is limited to about 6 MB.

body

TextBody

string

No

The text body of the email.

Note: Specify HtmlBody or TextBody.

  • The size of the parameter passed in a URL is limited to about 80 KB.

  • The size of the parameter passed in the body is limited to about 6 MB.

body

FromAlias

string

No

The nickname of the sender. The nickname must be fewer than 15 characters.

For example, if you set the nickname to "Alice" and the sender address is test***@example.net, the recipient sees the sender as "Alice" <test***@example.net>.

小红

ReplyAddress

string

No

The reply-to address.

test2***@example.net

ReplyAddressAlias

string

No

The nickname of the reply-to address.

小红

ClickTrace

string

No

1: enables data tracking.

0 (default): disables data tracking.

0

UnSubscribeLinkType

string

No

default: The default policy is used. An unsubscribe link is generated for batch emails sent to specific domains, such as domains that contain keywords like "gmail", "yahoo",

"google", "aol.com", "hotmail",

"outlook", or "ymail.com". For more information, see Unsubscribe link generation and filtering mechanism.

zh-cn: An unsubscribe link is generated for future instrumentation.

en-us: An unsubscribe link is generated for future instrumentation.

default

UnSubscribeFilterLevel

string

No

The filtering level. For more information, see Unsubscribe link generation and filtering mechanism.

disabled: Filtering is disabled.

default: The default policy is used. Batch addresses are filtered at the sender address level.

mailfrom: Filters at the sender address level.

mailfrom_domain: Filters at the email domain level.

edm_id: Filters at the account level.

mailfrom_domain

Headers

string

No

Add the following standard fields to the message header: Message-ID, List-Unsubscribe, and List-Unsubscribe-Post. Standard fields overwrite the original values in the message header. Non-standard fields must start with X-User- and are appended to the message header. Specify up to 10 message headers in JSON format. Both standard and non-standard fields must comply with the standard syntax for headers.

{ "Message-ID": "", "X-User-UID1": "UID-1-000001", "X-User-UID2": "UID-2-000001" }

IpPoolId

string

No

The ID of the dedicated IP address pool. If you purchased dedicated IP addresses, use this parameter to specify the outbound IP address for the current email. For more information, see Dedicated IPs.

e4xxxxxe-4xx0-4xx3-8xxa-74cxxxxx1cef

Attachments

array<object>

No

This feature is available only in the latest software development kit (SDK). It is not supported by OpenAPI or signature mechanisms. For more information, see How do I send an email with attachments using an SDK?.

object

No

This feature is available only in the latest SDK. It is not supported by OpenAPI or signature mechanisms.

AttachmentName

string

No

This feature is available only in the latest SDK. It is not supported by OpenAPI or signature mechanisms.

test.txt

AttachmentUrl

string

No

This feature is available only in the latest SDK. It is not supported by OpenAPI or signature mechanisms.

C:\Users\Downloads\test.txt

Template

object

No

The template information for sending template-based emails.

TemplateId

string

No

The template ID.

xxx

TemplateData

object

No

The variables and their values in the template.

string

No

The variables and their values in the template.

{ "name": "Tom", "age": "22" }

BccAddress

string

No

  • The list of blind carbon copy (BCC) recipients.

  • A copy of the email is sent to each BCC address. The BCC information is not visible to any recipient, including those in the ToAddress and BccAddress fields.

  • To protect the privacy of BCC recipients, email tracking is disabled by default for emails sent to BCC addresses. This means that behavioral data, such as open rates and click-through rates, is not recorded for BCC emails. However, billing, sending details, and sending status statistics are the same as for regular emails.

  • You can specify up to two BCC recipients for each email.

1@example.com,2@example.com

Response elements

Element

Type

Description

Example

object

EnvId

string

The event ID.

600000xxxxxxxxxx642

RequestId

string

The request ID.

2D086F6-xxxx-xxxx-xxxx-006DED011A85

Examples

Success response

JSON format

{
  "EnvId": "600000xxxxxxxxxx642",
  "RequestId": "2D086F6-xxxx-xxxx-xxxx-006DED011A85"
}

Error codes

HTTP status code

Error code

Error message

Description

400 InvalidReceiverName.Malformed The format of the receiver name is invalid. It must contain the @ sign. The domain must only contain numbers, letters, underscores, minus signs, and periods. The account name must only contain numbers, letters, underscores, minus signs, and periods. The format of the receiver name is invalid. It must contain the @ sign. The domain must only contain numbers, letters, underscores, minus signs, and periods. The account name must only contain numbers, letters, underscores, minus signs, and periods.
400 InvalidSubject.Malformed The specified subject is invalid. It must not exceed 100 characters. The specified subject is invalid. It must not exceed 256 characters.
404 InvalidMailAddress.NotFound The specified mail address is not found. The specified mail address is not found.

See Error Codes for a complete list.

Release notes

See Release Notes for a complete list.