Create a Campaign

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
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…

campaignJson

ParameterTypeRequiredDescription
taskTypeIntegerYesCampaign type. 1 = A/B campaign, 2 = normal campaign. Cannot be changed on update.
nameStringYesCampaign 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.
toStringYesRecipients. 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.
sendListTypeStringYesRecipient range type. "0" = all contacts, "1" = segment, "2" = tag.
senderIdStringYesSender 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.
replyToStringNoReply-to email address. Must be a valid email format when passed.
templateInvokeNameStringYesInvoke name of the sending template. Must exist under the current user, be a batch-type template, and have non-empty HTML content.
timeZoneStringYesTime zone of runTime. Numeric offset in hours from -12 to +12, e.g. "+8". Defaults to +8 when omitted.
zoneIdStringNoInternational city Id corresponding to the time zone. Defaults to the first city of the numeric offset when omitted.
runTimeStringYesSending 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.
googleTrackObjectNoGoogle 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.
warmUpConfigListArray (Object)NoWarm-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.
emptyExistedAttachmentsStringNoWhether 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.
abTestPercentStringYes (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.
abTestWinConditionObjectYes (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.
abTestItemConfigObjectYes (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

ParameterTypeRequiredDescription
campaignNameStringYes (when googleTrack is passed)Campaign name. Up to 64 characters.
campaignSourceStringYes (when googleTrack is passed)Campaign source. Up to 64 characters.
campaignMediumStringYes (when googleTrack is passed)Campaign medium. Up to 64 characters.
campaignTermStringNoCampaign keyword. Up to 64 characters.
campaignContentStringNoCampaign content. Up to 64 characters.

warmUpConfigList

ParameterTypeRequiredDescription
domainStringYes (per item)Receiving domain. Must be a valid domain format.
rateIntegerYes (per item)Sending rate per hour. 1-15; -1 means no rate limit (free); 0 is not allowed.
upgradeValueNumberYes (per item)Rate upgrade threshold. 0 < value < 1; must be greater than or equal to downgradeValue; rounded to 4 decimal places.
downgradeValueNumberYes (per item)Rate downgrade threshold. 0 < value < 1; rounded to 4 decimal places.

abTestWinCondition

ParameterTypeRequiredDescription
timeUnitIntegerYesTime unit. 1 = hour, 2 = day.
afterTimeIntegerYesTime before the winner is selected. 1-22 when timeUnit = 1 (hours); 1-10 when timeUnit = 2 (days).
compareIntegerYesComparison metric. 1 = open rate, 2 = click rate, 3 = unique open rate, 4 = unique click rate, 5 = delivered rate.

abTestItemConfig

ParameterTypeRequiredDescription
testItemTypeIntegerYesTest item type. 1 = subject, 2 = content, 3 = sender, 4 = send time.
templateSubjectStringYes (testItemType = 2)Subject shared by all test items. Up to 256 characters. Required when testItemType = 2; ignored for other test item types.
itemContentOneStringYesContent 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).
itemContentTwoStringYesContent of test item 2. Same rules as itemContentOne.
itemContentThreeStringNoContent of test item 3 (optional). Same rules as itemContentOne.

Notes

  1. When taskType=1 (A/B Test Task), if googleTrack and warmUpConfigList are passed, their values will be ignored and set to null by the system. These parameters can be omitted or passed as null.
  2. When taskType=1 (A/B Test Task), abTestPercent, abTestWinCondition, timeUnit, afterTime, compare, abTestItemConfig and testItemType are required fields.
  3. When taskType=1 (A/B Test Task), at least 2 of the three test items itemContentOne, itemContentTwo, itemContentThree must be provided.
  4. When taskType=1 (A/B Test Task), itemContentOne, itemContentTwo, itemContentThree are three values for the same test item category and must not be duplicated. runTime must be the earliest time among these three values.
  5. When taskType=2 (Regular Task), if googleTrack is set, campaignName, campaignSource and campaignMedium are required fields. googleTrack can be omitted or passed as null.
  6. When taskType=2 (Regular Task), if warmUpConfigList is set, domain, rate, upgradeValue and downgradeValue are required fields. warmUpConfigList can be omitted or passed as null.
  7. runTime must be later than the current time in the specified timeZone.
  8. Total of 33 parameters.
Body Params
string
required

Campaign configuration as a JSON string (structure described in the CampaignJson schema)

attachments
array of files

Attachment files (optional; only for normal campaigns with taskType=2). Up to 10 files; the suffix js, com, exe, sh, cs is not allowed; single file up to 10M (20M for big-attachment users), total size up to 10M (50M for big-attachment users).

Responses

Language
Credentials
Bearer
base64(apiUser:apiKey)
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json