createEmailCampaign: eBay Marketing API

POST/email_campaign

This method creates a new email campaign. An eBay store owner can create six different types of email campaigns: Welcome, New products & collections, Coupon, Sale event + markdown, Order discount, and Volume pricing.

A successful createEmailCampaign request returns the emailCampaignId assigned to the new email campaign.

The fields emailCampaignType, audienceCodes, itemSelectMode, subject, and personalizedMessage are required for all email campaign types.

Specific email campaign types have required values for additional fields. For more information on the email campaign types, see the Store Email Campaigns section of the Selling Integration Guide.

Input

Resource URI

POST https://api.ebay.com/sell/marketing/v1/email_campaign

This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com

URI parameters

This method has no URI parameters.

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.

Header Type Description

Header	Type	Description
Content-Type	string	This header indicates the format of the request body provided by the client. Its value should be set to application/json. For more information, refer to HTTP request headers. Occurrence: Required
X-EBAY-C-MARKETPLACE-ID	string	The eBay marketplace that the email campaign interfaces with. eBay marketplaces correspond to geographical regions or large submarkets of regions. For example, `EBAY-US` corresponds to the United States market. See MarketplaceIdEnum for supported values. Occurrence: Required

Content-Type

string

This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers.

Occurrence: Required

X-EBAY-C-MARKETPLACE-ID

string

The eBay marketplace that the email campaign interfaces with.

eBay marketplaces correspond to geographical regions or large submarkets of regions. For example, EBAY-US corresponds to the United States market.

See MarketplaceIdEnum for supported values.

Occurrence: Required

OAuth scope

This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/sell.marketing

See OAuth access tokens for more information.

Request payload

Copy complete valid JSON to clipboard

{ /* CreateEmailCampaignRequest */

"audienceCodes" : [

"string"

"categoryId" : "string",

"categoryType" : "CategoryTypeEnum : [EBAY,STORE]",

"emailCampaignType" : "CampaignTypeEnum : [WELCOME,ITEM_SHOWCASE,COUPON...]",

"itemIds" : [

"string"

"itemSelectMode" : "ItemSelectModeEnum : [AUTO,MANUAL]",

"personalizedMessage" : "string",

"priceRange" :

{ /* PriceRange */

"currency" : "string",

"gte" : "number",

"lte" : "number"

"promotionId" : "string",

"promotionSelectModeEnum" : "PromotionSelectModeEnum : [AUTO,MANUAL]",

"scheduleDate" : "string",

"sort" : "ItemSortEnum : [ENDING_FIRST,HIGHEST_PRICED,LOWEST_PRICED...]",

"subject" : "string"

}

Request fields

Input container/field	Type	Description
audienceCodes	array of string	An array of audience codes for the audiences of the email campaign. At least one audience code is required. There is no upper limit to the number of audience codes. To retrieve seller audiences, call getAudiences. Use the code values in the response to populate audienceCodes. Occurrence: Required
categoryId	string	The unique identifier of either an eBay category or a store category. This field is used if a seller wants to apply an email campaign to a specific eBay category or store category. The categoryType determines whether the categoryId value is an eBay category or store category. To retrieve eBay categories, use the getCategories or Taxonomy API. To retrieve seller store categories, use the getStore call. Use the categoryId value of the desired category from the results as the value in the request. itemSelectMode must be set to `AUTO` in order to use a category ID. Occurrence: Conditional
categoryType	CategoryTypeEnum	This field must be set when applying an email campaign to a specific eBay category or store category. The enumeration value used indicates which type of category the categoryId belongs to. Occurrence: Optional
emailCampaignType	CampaignTypeEnum	The email campaign type of the email campaign being created. There are six email campaigns that a user can create: `WELCOME` - an email sent automatically to new subscribers. `ITEM_SHOWCASE` - an email featuring new products & collections that the seller wants to highlight. `COUPON` - an email containing a coupon code and up to 4 items that this coupon can be applied to. `ORDER_DISCOUNT` - an email containing an order discount and up to 10 items that this discount can be applied to. `SALE_EVENT` - an email about a sale event and up to 10 items that the sale can be applied to. `VOLUME_PRICING` - an email containing up to 10 items that are eligible for volume pricing. Note: emailCampaignType cannot be updated once the email campaign is created. Occurrence: Required
itemIds	array of string	An array of unique identifiers for the listings displayed in an email campaign. Used if the seller wishes to select the eBay listings in the email campaign rather than have eBay automatically select them. Call getSellerList to retrieve all seller listings. Each Item result contains an ItemID value. Use this value in itemIds to feature that listing. The maximum number of itemIds for the `COUPON` campaign type is 4, and for every other campaign type is 10 itemSelectMode must be set to `MANUAL` in order to use this field. Occurrence: Conditional
itemSelectMode	ItemSelectModeEnum	Determines whether listings featured in an email campaign are selected by the seller or by eBay. If itemSelectMode is set to `AUTO`, eBay automatically choses listings based on values set for sort, categoryType, categoryId, and priceRange. If itemSelectMode is set to `MANUAL`, listings are set by the seller by populating the itemIds array. Note: itemSelectMode is always set to `AUTO` for `WELCOME` email campaigns. Occurrence: Required
personalizedMessage	string	The body of the email campaign. Accepts HTML and CSS. Max length: 1000 Occurrence: Required
priceRange	PriceRange	This container is used if the seller wants to apply the email campaign to listings based on a price range. The priceRange container consists of the currency, gte, and lte fields. "gte" stands for "greater than or equal to" and "lte" stands for "less than or equal to". Either gte, lte, or both must be used. currency is a required field if including a price range. One of the three-digit currency codes from CurrencyCodeEnum must be specified. Note: Use this object when the itemSelectMode is set to `AUTO`. Occurrence: Optional
priceRange.currency	string	Specifies the currency of the listings in an email campaign using one of the three-digit codes of the CurrencyCodeEnum type. Occurrence: Conditional
priceRange.gte	number	The listings selected will be greater than or equal to this value. The value entered must be given in number format, such as 20.00. Either `gte`, `lte`, or both must contain a value if the seller wishes to use a price range. Occurrence: Optional
priceRange.lte	number	The listings selected will be less than or equal to this value. The value entered must be given in number format, such as 100.00. Either `gte`, `lte`, or both must contain a value if the seller wishes to use a price range. Occurrence: Optional
promotionId	string	The unique identifier of the promotion used for an email campaign if the emailCampaignType is set to `COUPON`, `SALE_EVENT`, or `ORDER_DISCOUNT`. promotionSelectModeEnum must set to `MANUAL` if a promotion is selected. Call getPromotions to retrieve a list of the seller's promotions. Use the promotionId from an individual PromotionDetail in the result to populate the request. Occurrence: Conditional
promotionSelectModeEnum	PromotionSelectModeEnum	The selection mode for the promotion used if the emailCampaignType is set to `COUPON`, `SALE_EVENT`, or `ORDER_DISCOUNT`. If promotionSelectModeEnum is set to `AUTO`, eBay will choose the promotion to include in the email campaign. If set to `MANUAL`, the seller must specify the promotion in the promotionId field. Occurrence: Conditional
scheduleDate	string	The date and time that the email campaign newsletter will be sent, given in UTC format. Example: 2023-05-20T03:13:35Z This field should be used if the seller wishes to send the email campaign on a future date. If no scheduleDate is set, the email campaign will send once it is created or updated. Occurrence: Optional
sort	ItemSortEnum	The sort rule is used to display the listings featured in the email campaign. Sort rules are only used if itemSelectMode is set to `AUTO`. If itemSelectMode is `MANUAL`, listings are displayed in the order in which they are listed in the itemIds array. The following sort rules are available: `ENDING_FIRST` displays listings by ending date, from soonest to latest. `LOWEST_PRICED` displays listings by price, from lowest to highest. `HIGHEST_PRICED` displays listings by price, from highest to lowest. `NEWLY_LISTED` displays listings by date listed, with the newest first. The default sort rule is `NEWLY_LISTED`. Occurrence: Conditional
subject	string	The subject line of the email campaign. Max length: 70 Occurrence: Required

Output

HTTP response headers

This call has no response headers.

Response payload

Copy complete valid JSON to clipboard

{ /* CreateEmailCampaignResponse */

"emailCampaignId" : "string",

"emailCampaignStatus" : "EmailCampaignStatusEnum : [ACTIVE,SENT,ERROR]"

}

Response fields

Output container/field Type Description

Output container/field	Type	Description
emailCampaignId	string	The unique eBay-assigned identifier of the email campaign. It is generated automatically when the email campaign is created. This value is returned unless there is an error. Occurrence: Always
emailCampaignStatus	EmailCampaignStatusEnum	The status of the email campaign. `ACTIVE` is returned for email campaigns that have been successfully created but not been sent. `SENT` is returned for email campaigns that have already been sent. `ERROR` is returned when an email has not been successfully created. Occurrence: Always

emailCampaignId

string

The unique eBay-assigned identifier of the email campaign. It is generated automatically when the email campaign is created.

This value is returned unless there is an error.

Occurrence: Always

emailCampaignStatus

EmailCampaignStatusEnum

The status of the email campaign.

ACTIVE is returned for email campaigns that have been successfully created but not been sent.

SENT is returned for email campaigns that have already been sent.

ERROR is returned when an email has not been successfully created.

Occurrence: Always

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

Status	Meaning
200	OK
400	Bad Request
500	Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

Code	Domain	Category	Meaning
35000	STORE_CRM	APPLICATION	Internal server error encountered. If this problem persists, contact the eBay Developers Program for support.
35001	STORE_CRM	BUSINESS	A store subscription is required for this call, please check the store subscription status for current seller.
35201	STORE_CRM	REQUEST	'marketplaceId' value is not supported. For the valid values, see the documentation for this call.
35202	STORE_CRM	REQUEST	'emailCampaignType' value is not supported. For the valid values, see the documentation for this call.
35203	STORE_CRM	REQUEST	'audiences' is required for this call.
35204	STORE_CRM	REQUEST	'subject' is required for this call.
35205	STORE_CRM	REQUEST	'personalizedMessage' is required for this call.
35206	STORE_CRM	REQUEST	'subject' length is too long. For maximum limits, see the documentation for this call.
35207	STORE_CRM	REQUEST	'audiences' value is not suitable for current email campaign type.
35208	STORE_CRM	REQUEST	'itemIds' is required for this call.
35209	STORE_CRM	REQUEST	For 'WELCOME' type campaign, 'itemIds' should be empty.
35210	STORE_CRM	REQUEST	The item {itemIds} size exceeds maximum. For maximum limits, see the documentation for this call.
35211	STORE_CRM	REQUEST	No eligible items for current campaign.
35212	STORE_CRM	REQUEST	'promotionId' is required for this call.
35213	STORE_CRM	REQUEST	'promotionId' is invalid, promotion may be inactive or non-exist.
35214	STORE_CRM	REQUEST	'scheduleDate' is not required for this call.
35215	STORE_CRM	REQUEST	'scheduleDate' is missing or invalid, please use a valid UTC format(yyyy-MM-ddThh:mm.sssZ) string.
35216	STORE_CRM	REQUEST	Only one 'WELCOME' type email campaign is allowed for one marketplace.
35217	STORE_CRM	REQUEST	Only one automated promotion email campaign is allowed for one campaign type per marketplace id.
35218	STORE_CRM	REQUEST	'personalizedMessage' length is too long. For maximum limits, see the documentation for this call.
35219	STORE_CRM	REQUEST	The email campaign schedule date {scheduleDate} must be in the future.
35220	STORE_CRM	REQUEST	'itemIds' contains ineligible item id, please check the item list
35221	STORE_CRM	REQUEST	'itemSelectMode' is invalid for this campaign, please see the documentation for this call.

Warnings

This call has no warnings.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Creating an Email Campaign

This method creates a new email campaign.

Input

No query or URI path parameters are needed for this call.

In this sample, an ITEM_SHOWCASE email campaign is being created, as specified by the emailCampaignType field. This email campaign type is used to feature new products and collections that a seller wants to highlight. The campaign is being sent to all subscribers and followers of the seller's store, as specified by the audiences container and is scheduled to be sent at 2023-04-13T02:50:13.000Z. A subject and personalizedMessage have also been added to let the audience know that this is a test email campaign.

POSThttps://api.ebay.com/sell/marketing/v1/email_campaign

Output

If the call is successful, the emailCampaignId and emailCampaignStatus for the created email campaign are returned.