post
https://api.aurorasendcloud.com/marketing/campaigns
Create a marketing campaign (multipart/form-data). The campaignJson part carries the campaign configuration as a JSON string; the attachments part is only supported by normal campaigns (taskType=2). The runTime must be later than the current time in the given time zone, and the sending quota is checked on creation.
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
campaignJson
| Parameter | Type | Required | Description |
|---|---|---|---|
| taskType | Integer | Yes | Campaign type. 1 = A/B campaign, 2 = normal campaign. Cannot be changed on update. |
| name | String | Yes | Campaign name. Up to 64 characters; must be unique among campaigns of the same type under the current user; also saved as the email subject of the campaign. |
| to | String | Yes | Recipients. Pass all when sendListType = 0 (the contact list must exist and contain at least one contact); pass a segment Id when sendListType = 1 (the segment must exist and belong to the current user); pass a tag Id when sendListType = 2 (the tag must exist and belong to the current user). The recipient range must contain at least one contact. |
| sendListType | String | Yes | Recipient range type. "0" = all contacts, "1" = segment, "2" = tag. |
| senderId | String | Yes | Sender Id (numeric string). The sender must exist and belong to the current user, and the API_USER bound to the sender must be a batch-type API_USER. |
| replyTo | String | No | Reply-to email address. Must be a valid email format when passed. |
| templateInvokeName | String | Yes | Invoke name of the sending template. Must exist under the current user, be a batch-type template, and have non-empty HTML content. |
| timeZone | String | Yes | Time zone of runTime. Numeric offset in hours from -12 to +12, e.g. "+8". Defaults to +8 when omitted. |
| zoneId | String | No | International city Id corresponding to the time zone. Defaults to the first city of the numeric offset when omitted. |
| runTime | String | Yes | Sending time. Format yyyy-MM-dd HH:mm:ss; must not be earlier than the current time in the given time zone; for A/B campaigns with testItemType = 4, runTime must be the earliest time among all test item send times. |
| googleTrack | Object | No | Google Analytics tracking configuration. Only effective for normal campaigns (taskType = 2); ignored when all five fields are empty. On update, pass to delete the configuration; omit the field or null to keep it unchanged. |
| warmUpConfigList | Array (Object) | No | Warm-up rate configuration. Only effective for normal campaigns (taskType = 2); up to 20 domains, duplicate domains are not allowed. On update, pass [] to delete the configuration; omit the field or null to keep it unchanged. |
| emptyExistedAttachments | String | No | Whether to clear existing attachments on update. 1 = clear, 0 = keep. Only takes effect on update, and only when no new attachments are passed; ignored when new attachments are passed; no effect on creation. |
| abTestPercent | String | Yes (taskType = 1) | A/B test ratio. Numeric string from 1 to 100; e.g. 20 means 20% of the recipients are selected as the test group. |
| abTestWinCondition | Object | Yes (taskType = 1) | A/B test win condition. After the specified time the winner is selected by the comparison metric and sent to the remaining recipients. |
| abTestItemConfig | Object | Yes (taskType = 1) | A/B test item configuration. At least 2 and at most 3 non-blank, non-duplicate test items are required, and the number of recipients must not be less than the number of test items. |
googleTrack
| Parameter | Type | Required | Description |
|---|---|---|---|
| campaignName | String | Yes (when googleTrack is passed) | Campaign name. Up to 64 characters. |
| campaignSource | String | Yes (when googleTrack is passed) | Campaign source. Up to 64 characters. |
| campaignMedium | String | Yes (when googleTrack is passed) | Campaign medium. Up to 64 characters. |
| campaignTerm | String | No | Campaign keyword. Up to 64 characters. |
| campaignContent | String | No | Campaign content. Up to 64 characters. |
warmUpConfigList
| Parameter | Type | Required | Description |
|---|---|---|---|
| domain | String | Yes (per item) | Receiving domain. Must be a valid domain format. |
| rate | Integer | Yes (per item) | Sending rate per hour. 1-15; -1 means no rate limit (free); 0 is not allowed. |
| upgradeValue | Number | Yes (per item) | Rate upgrade threshold. 0 < value < 1; must be greater than or equal to downgradeValue; rounded to 4 decimal places. |
| downgradeValue | Number | Yes (per item) | Rate downgrade threshold. 0 < value < 1; rounded to 4 decimal places. |
abTestWinCondition
| Parameter | Type | Required | Description |
|---|---|---|---|
| timeUnit | Integer | Yes | Time unit. 1 = hour, 2 = day. |
| afterTime | Integer | Yes | Time before the winner is selected. 1-22 when timeUnit = 1 (hours); 1-10 when timeUnit = 2 (days). |
| compare | Integer | Yes | Comparison metric. 1 = open rate, 2 = click rate, 3 = unique open rate, 4 = unique click rate, 5 = delivered rate. |
abTestItemConfig
| Parameter | Type | Required | Description |
|---|---|---|---|
| testItemType | Integer | Yes | Test item type. 1 = subject, 2 = content, 3 = sender, 4 = send time. |
| templateSubject | String | Yes (testItemType = 2) | Subject shared by all test items. Up to 256 characters. Required when testItemType = 2; ignored for other test item types. |
| itemContentOne | String | Yes | Content of test item 1. Meaning depends on testItemType: subject text when testItemType = 1 (each up to 256 characters); template invoke name when testItemType = 2 (each must exist, be a batch-type template with non-empty HTML content); sender Id when testItemType = 3 (each must exist); send time yyyy-MM-dd HH:mm:ss when testItemType = 4 (runTime must be the earliest among all item send times). |
| itemContentTwo | String | Yes | Content of test item 2. Same rules as itemContentOne. |
| itemContentThree | String | No | Content of test item 3 (optional). Same rules as itemContentOne. |
Notes
- When
taskType=1(A/B Test Task), ifgoogleTrackandwarmUpConfigListare passed, their values will be ignored and set tonullby the system. These parameters can be omitted or passed asnull. - When
taskType=1(A/B Test Task),abTestPercent,abTestWinCondition,timeUnit,afterTime,compare,abTestItemConfigandtestItemTypeare required fields. - When
taskType=1(A/B Test Task), at least 2 of the three test itemsitemContentOne,itemContentTwo,itemContentThreemust be provided. - When
taskType=1(A/B Test Task),itemContentOne,itemContentTwo,itemContentThreeare three values for the same test item category and must not be duplicated.runTimemust be the earliest time among these three values. - When
taskType=2(Regular Task), ifgoogleTrackis set,campaignName,campaignSourceandcampaignMediumare required fields.googleTrackcan be omitted or passed asnull. - When
taskType=2(Regular Task), ifwarmUpConfigListis set,domain,rate,upgradeValueanddowngradeValueare required fields.warmUpConfigListcan be omitted or passed asnull. runTimemust be later than the current time in the specifiedtimeZone.- Total of 33 parameters.
