createMailRequest

Available in Classic and VPC

Request an email to be sent, specifying the recipient, sender, mail content, etc. The mailing operation is processed asynchronously.

Note

You can send up to 100,000 recipients at a time, and it is processed in batches of 30 by default. However, you can send more than 100,000 recipients when you enter the recipient group combination sending condition (recipientGroupFilter).
You can specify up to 30 recipients for Cc and Bcc.
Email bodies are allowed to be up to 500 KB.
The default sending limit is 1,000,000 per month, but you can request an increase through Support.
The sending request limit is calculated based on the number of email recipients. A send request for 100 recipients is considered 100 send requests.

Request

The following describes the request format for the endpoint. The request format is as follows:

Method	URI
POST	/mails

Request headers

For headers common to Cloud Outbound Mailer APIs, see Cloud Outbound Mailer request headers.

Request body

The following describes the request body.

Field	Type	Required	Description
`senderAddress`	String	Conditional	Sender's email address You can use any domain, but we recommend using a domain that the sender actually owns Using a webmail account on a portal site with DMARC applied, such as " id@naver.com," "id@navercorp.com," and "id@ncloud.com," might fail the DMARC check and be treated as spam according to the recipient's policies Required when not setting `templateSid` The domain cannot be naver.com. navercorp.com, etc.
`senderName`	String	Optional	Sender's name (byte) 0 - 69
`templateSid`	Integer	Optional	SID of the template you want to use to create the email Check through getTemplateStructure
`title`	String	Conditional	Email subject (byte) 0 - 500 Required if `templateSid` is not set
`body`	String	Conditional	Email body (KB) 0 - 500 (Advertising emails are counted including unsubscribe messages) Required if `templateSid` is not set
`individual`	Boolean	Optional	Whether to send generally or by individual `true` (default) \| `false` `true`: individual delivery `false`: general delivery You can only enter an `R` (recipient) in `recipients` when sending individually. When entering multiple values, they are sent separately to each individual
`confirmAndSend`	Boolean	Optional	Whether to send after confirmation `true` \| `false` `true`: send after confirmation `false`: send immediately without confirmation
`advertising`	Boolean	Optional	Whether it is advertising email `true` \| `false` `true`: advertising email `false`: general email
`parameters`	Object	Optional	Substitution parameter It applies to all recipients A map-type object with substitution IDs as keys and the values that map to the substitution IDs as values See User Guide for the detailed application method
`referencesHeader`	String	Optional	References header A string of 20 to 100 characters in the format of unique_id@domain.com Unique value for collecting and viewing specific emails If you enter a value in the field, you can collect and view only emails with the same value in the future. It is used in NAVER Mail to collect and view emails If the value is duplicated, it is determined to be the same email thread and the emails are grouped together Only the topmost value of the References header is used to determine
`reservationUtc`	Long	Optional	Reserved delivery date and time Number of milliseconds that have elapsed since January 1, 1970 00:00:00 UTC Can be from the current point in time up to 30 days in the future Take precedence over the `reservationDateTime` value
`reservationDateTime`	String	Optional	Reserved delivery date and time (yyyy-MM-dd HH:mm) Based on UTC+9:00 Can be from the current point in time up to 30 days in the future The `reservationUtc` value takes precedence
`attachFileIds`	List<String>	Optional	ID list of attachments Check the file ID through createFile The total size of the files must be 20 MB or less
`recipients`	List<RecipientForRequest>	Conditional	Recipient list Must be entered if there is no `recipientGroupFilter` value
`recipientGroupFilter`	RecipientGroupFilter	Optional	Recipient group combination filter
`useBasicUnsubscribeMsg`	Boolean	Optional	Whether to use unsubscribe messages in advertising email `true` (default) \| `false` `true`: Use the default unsubscribe message `false`: Use custom unsubscribe message Unsubscribe message size is approximately 900 bytes
`unsubscribeMessage`	String	Conditional	Custom unsubscribe message text Append after `body` value by default Enter the `#{UNSUBSCRIBE_MESSAGE}` tag at the desired location in the `body` value to insert it inside the mail content Required if the useBasicUnsubscribeMsg value is `false` Must be 500 KB or less combined with `body`

Request example

The following is a sample request.

Create without template

The following is a sample request for writing your own email content without using a template.

curl --location --request POST 'https://mail.apigw.ntruss.com/api/v1/mails'
--header 'x-ncp-apigw-timestamp: {Timestamp}'
--header 'x-ncp-iam-access-key: {Access Key}'
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}'
--header 'Content-Type: application/json'
--data-raw '{"senderAddress":"no_reply@company.com","title":"Hello, ${customer_name}.","body":"Your grade has been changed from ${BEFORE_GRADE} to ${AFTER_GRADE}.","recipients":[{"address":"hongildong@naver_.com","name":"Gildong Hong","type":"R","parameters":{"customer_name":"Gildong Hong","BEFORE_GRADE":"SILVER","AFTER_GRADE":"GOLD"}},{"address":"chulsoo@daum_.net","name":null,"type":"R","parameters":{"customer_name":"Chulsoo","BEFORE_GRADE":"BRONZE","AFTER_GRADE":"SILVER"}}],"individual":true,"advertising":false}'

Create with template

The following is a sample request for writing your own email content using a template.

curl --location --request POST 'https://mail.apigw.ntruss.com/api/v1/mails'
--header 'x-ncp-apigw-timestamp: {Timestamp}'
--header 'x-ncp-iam-access-key: {Access Key}'
--header 'x-ncp-apigw-signature-v2: {API Gateway Signature}'
--header 'Content-Type: application/json'
--data-raw '{"templateSid" : 1,"recipients":[{"address":"hongildong@naver_.com","name":"Gildong Hong","type":"R","parameters":{"customer_name":"Gildong Hong","BEFORE_GRADE":"SILVER","AFTER_GRADE":"GOLD"}},{"address":"chulsoo@daum_.net","name":null,"type":"R","parameters":{"customer_name":"Chulsoo","BEFORE_GRADE":"BRONZE","AFTER_GRADE":"SILVER"}}],"individual":true,"advertising":false}'

Response

The following describes the response format.

Response body

The following describes the response body.

Field	Type	Required	Description
`requestId`	String	Required	Email delivery request ID to distinguish each request `requestId` can contain multiple `mailId` when requesting multiple mailings at once
`count`	Integer	Required	Number of mailing requests

Response status codes

The following describes the response status codes.

HTTP status code	Code	Description
201	-	Request succeeded
400	-	Authentication failed, invalid request
400	77101	Error in login information
400	77102	Request error
400	77103	Requested resource does not exist
403	77201	No permissions to the requested resource
403	77202	Call from a user who hasn't subscribed to the email service
405	77001	Unsupported method type
415	77002	Unsupported media type
500	-	Server error
500	77301	Default project does not exist
500	77302	External system API integration error
500	77303	Other internal server error

Response example

The following is a sample response.

{
  "requestId":"20181203000000000201",
  "count":10000
}