Store Email Campaigns

Email marketing is one of the most powerful ways for reaching out to customers and building a community of repeat buyers. An eBay store seller can easily create and send email campaigns to subscribers, followers, and past customers who have signed up to receive newsletters. Sellers can use the newsletter to welcome customers, let them know about new listings promotions, sales, and discounts.

The new email_campaign resource in Sell marketing API has eight new methods. There are methods for creating, updating, and deleting email campaigns, as well as methods for retrieving email campaigns, obtaining previews of email content, obtaining metrics on email campaigns, and retrieving email campaign audiences.

The Marketing API works with listings that have been created with the Trading API, as well as items that are managed with the Inventory API.

Creating, updating, and deleting email campaigns

Sellers can use the createEmailCampaign method to create any of the available email campaign types. Sellers can only create one email campaign at a time. The request accepts fields that specify details of the email campaign, such as type, featured listings, email content, audiences, and more, as explained in the creating email campaigns section.

updateEmailCampaign is used to make changes to an existing email campaign. Certain fields cannot be changed once created, as outlined in the updating email campaign section.

deleteEmailCampaign deletes one email campaign at a time and returns the unique identifier of that email campaign if the deletion has been successful.

Additional methods

The following additional methods are also available: 

• getEmailCampaigns retrieves a seller's email campaigns. Using the path parameters, sellers can filter which campaigns are returned and how the results are displayed.

• getEmailCampaign returns the details of a single email campaign.

• getAudiences returns details on the available audiences for a particular email campaign type. Among these are eBay standard audiences and custom seller-created audience groups.

• getEmailPreview returns the contents of an email campaign, which can be used directly in other applications.

• getEmailReport returns data on user engagement for a seller's email campaigns.

Selecting email recipients and using the getAudiences method

Every email campaign requires at least one audience from the table below. Sellers can set this value as a string array in audienceCodes .

Available audience types

The following audience types are available to store sellers:

Audience type	Enum value	Description
All subscribers	ALL_SUBSCRIBERS	All the subscribers to a seller store.
New subscribers	NEW_SUBSCRIBERS	All subscribers added to the seller store in the past 30 days.
First time buyers	FIRST_TIME_BUYERS	First time buyers from the seller store, regardless of when they made their purchase.
Recent buyers	RECENT_BUYERS	Buyers who have made a purchase from the seller store between the last 31 - 365 days.
Most recent buyers	MOST_RECENT_BUYERS	Buyers who have made a purchase from the seller store within the last 30 days.
Interested buyers	INTERESTED_BUYERS	Users who have marked that they are interested in a product from the seller store.
Followers	FOLLOWERS	Users who follow the seller store.
New followers	NEW_FOLLOWERS	Users who started following the seller store within the last 30 days.
Post-campaign new buyers	POST_CMPGN_NEW_BUYERS	Users who became new buyers from the seller store after an email campaign.
Buyer group	BUYER_GROUP	A group that has been created by the store seller to receive coded coupons. See buyer groups for more information.
Custom audience	CUSTOM	An audience created by the store seller that is comprised of manually selected buyers selected from their subscribers.

Creating custom audiences

Custom audiences fall under either the Buyer group or Custom audience type. Buyer groups are created using various conditions.

For example, a buyer group can be for users to have bought from a specific category, within a specific timeframe, from a specific category within a specific timeframe, and so on.

Using getAudiences method

When creating a new email campaign, users can first call getAudiences to retrieve a list of audiences available for the email campaign type they are creating.

Specify the emailCampaignType query parameter. For example, the following method retrieves all audiences available for a Welcome email campaign for the seller's eBay store:

GET https://api.ebay.com/sell/marketing/v1/email_campaign/audience?emailCampaignType=WELCOME

getAudiences returns an array of audiences containing a name, code, and audienceType value.

For all audience types except Buyer group and Custom, the name, code, and audienceType values are the same.

Buyer groups and Custom audiences have a name that was assigned by the seller and a code string value assigned automatically by eBay, as seen below:

"audiences": [
	{
		"name": "previous customers",
		"code": "15575482369",
		"audienceType": "ALL_SUBSCRIBERS"
	}
]

Use the code value to populate the audienceCodes array in the email campaign request.

For instance, to create an email campaign showcasing new listings to a buyer group "previous customers", the request would contain:

"audienceCodes": ["15575482369"]

Creating email campaigns using createEmailCampaign

The createEmailCampaign method is used to create a new email campaign.

Creating a request follows the same procedures for all campaign types. Five fields are required fields for every email campaign type:

• emailCampaignType

• audienceCodes

• itemSelectMode

• personalizedMessage

• subject

Setting the email campaign type

The emailCampaignType field indicates the type of email campaign.

There are six different email campaign types available to store sellers: Welcome, New products & collections, Coupons, Sale event & markdown, Order discounts, and Volume pricing email campaigns.

All campaign types required the following fields: 

• At least one audienceCodes value

• emailcampaignType

• itemSelectMode

• personalizedMessage

• subject

When creating or updating certain email campaign types, additional fields must be assigned specific values for that particular campaign type.

Welcome email campaign

The Welcome email campaign is sent automatically to new subscribers once a seller creates a campaign and includes the audience code for NEW_SUBSCRIBERS.

Additional mandatory values:

"emailCampaignType": "WELCOME",
"itemSelectMode": "AUTO"	

Because the itemSelectMode is set to AUTO, the seller cannot manually select any listings for this campaign.

New products & collections email campaign

This email campaign is used to feature new products and collections that the seller wants to highlight. To do this, a seller can either manually select items to be included in this campaign, or set the itemSelectMode to AUTO and apply Category ID filters.

Additional mandatory fields:

"emailCampaignType": "ITEM_SHOWCASE"

Volume pricing email campaign

This email campaign contains items that are eligible for volume pricing. To do this, a seller can either manually select up to 10 items to be included in this campaign, or set the itemSelectMode to AUTO and apply Category ID filters.

Additional mandatory fields:

"emailCampaignType": "VOLUME_PRICING",
"categoryType": "STORE"

A store category must be attached to this type of email campaign. Set categoryType to STORE and set the store category in categoryId. For more information on store categories, see Using Categories.

Coupon email campaign

This email contains a coupon code and up to 4 items that this coupon can be applied to.

Additional mandatory fields:

"emailCampaignType": "COUPON"

This email campaign type uses the promotionSelectModeEnum field to indicate whether the promotion, or coupon, is selected automatically by eBay or manually by the seller.

Sale event & markdown email campaign

This email campaign contains a notice about a sale event and up to 10 items that the sale can be applied to.

Additional mandatory fields:

"emailCampaignType": "SALE_EVENT"

Set promotionSelectModeEnum to indicate whether the promotion is selected automatically by eBay or manually by the seller.

Order discount email campaign

This email campaign contains an order discount and up to 10 items that this discount can be applied to.

Additional mandatory fields:

"emailCampaignType": "ORDER_DISCOUNT"

This email campaign uses the promotionSelectModeEnum field to indicate whether the promotion is selected automatically by eBay or manually by the seller.

Setting the audience

The audienceCodes array determines who receives the email campaign. The numeric codes needed for this input can be retrieved using the getAudiences method.

Auto and Manual item selection

The store email campaign methods provide auto and manual modes for selecting these listings, indicated by the itemSelectMode field.

Manual mode

The seller chooses the listings to include in the email campaign by including their item IDs into the itemIdsarray.

The GetSellerList call of the Trading API can be used to retrieve item ID values. Use the ItemID values in the individual Item results to populate the itemIds array in the request.

If using the manual item selection mode, you do not need to set the following fields, as they are used to help eBay select the featured listings in auto mode: sort, categoryType, categoryId, and priceRange.

Item ID values are delimited with a comma.

Auto mode

In auto mode, the eBay system selects listings using values from the following fields: priceRange, categoryType, categoryId, sort

In this case, do not use the itemIds array.

Below is an example of selecting auto item selection mode and setting category and price range filters:

"itemSelectMode": "AUTO",
"priceRange": {
	"currency": "USD",
	"lte": 100.00,
	"gte": 10.00
},
"categoryType": "EBAY",
"categoryId": "9355",
"sort": "HIGHEST_PRICED"

For more information on the priceRange array shown above, see Setting a price range. For more information on categoryType and CategoryId, see Using categories.

Setting a price range

The price range is an optional container that contains three fields:

• lte - 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.
• gte - 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.
• currency - The currency of the listings in an email campaign using one of the three-digit codes of the CurrencyCodeEnum type.

The seller has an option to use lte, gte, or both. If only lte is included and set to 100.00, all items priced $100 or less are added to the campaign. If only gte is included and set to 100.00, all items priced $100 or more are added to the campaign. If gte is set to 20.00 and lte is set to 100.00, all items priced between $20 and $100 are added to the campaign.

If using a price range, currency and lte or gte are conditionally required.

Using categories

Sellers can attach a category to the email campaign. There are two kinds of categories available: eBay categories and store categories. eBay categories are all categories available across eBay. Store categories are categories defined by the seller in the context of available items in their store.

Set the category using two fields: categoryType and categoryId.

categoryId contains the specific category identifier. categoryType indicates whether the categoryId pertains to an eBay or store category.

To retrieve eBay categories, use the GetCategories call of the Trading API or use the Taxonomy API. Store category IDs are returned in the CustomCategory.CategoryID field of the GetStore call of the Trading API. Use the categoryId value of the desired category from the results as the value in the request.

Sorting listings

The sort field determines the sort rule by which listings are displayed in the email campaign.

The default sort rule is NEWLY_LISTED. See ItemSortEnum for all available sort rules.

Item promotions

Coupon, Sale event & markdown, and Order discount campaigns are all considered item promotion and require the use of the promotionSelectModeEnum and promotionId fields.

Promotions are set using the promotionSelectModeEnum and promotionId fields.

Promotion selection can be either auto or manual.

Manual promotion selection

To select a promotion manually, set "promotionSelectModeEnum": "MANUAL".

Set promotionId with the unique ID of the desired promotion.

Promotion IDs can be viewed by the seller under the Marketing tab of the Seller Hub. getPromotions can also be called to retrieve a list of the seller's promotions. Use the promotionId from an individual PromotionDetail in the result to populate the request.

Automatic promotion selection

To let eBay select the promotion, set "promotionSelectModeEnum": "AUTO". Do not set the promotionId field.

Scheduling an email campaign

Sellers can use the scheduleDate field to set a future date for the email campaign release. Enter the date as a string in UTC format.

For instance:

"scheduleDate": "2023-05-20T03:13:35Z"			

If no scheduleDate is set, the email campaign will send once it is created or updated.

Subject line and email body

The subject line and email body are required when creating an email campaign.

Set the subject line as a string in the subject field. The maximum length is 70 characters.

Set the email body in the personalizedMessage field. This field should be a string value, and accepts HTML and CSS. The maximum length is 1000 characters.

Updating email campaigns

The updateEmailCampaign method is used to update a single email campaign at a time. This method requires the unique email campaign ID to be passed into the email_campaign_id path parameter.

To obtain the email_campaign_id call the getEmailCampaigns method.

Use the emailCampaignId value of the campaign you wish to delete as the email_campaign_id path parameter in the updateEmailCampaign call.

Those fields that have required values for each campaign type cannot be updated once the email campaign is created. The following is a list of email campaign types and those fields that cannot be updated:

• Welcome email campaigns: emailCampaignId, emailCampaignType, itemSelectMode
• New campaigns & collections email campaigns: emailCampaignId, emailCampaignType
• Coupon email campaigns: emailCampaignId, emailCampaignType
• Sale event & markdown email campaigns: emailCampaignId, emailCampaignType
• Order discount email campaigns: emailCampaignId, emailCampaignType
• Volume pricing email campaigns: emailCampaignId, emailCampaignType, categoryType

For updating all other fields, refer to the guidelines outlined in the Create Email Campaign section.

Retrieving email campaigns

Sellers can retrieve either many email campaigns, filtering results using parameters, or a single email campaign.

Retrieving all email campaigns

The getEmailCampaigns method is called to retrieve all of a store seller's email campaigns. Filter the results returned and their display using the query parameters.

The q parameter filters which results are returned, and the limit, offset, and sort parameters regulate how the results are displayed.

Using the q parameter

q accepts values for campaignType, status, and marketplaceID. Each filter accepts a comma separated list of values.

campaignType specifies which of the six campaign types a seller would like to return. For instance, to return all Coupon and Order discount campaigns, set q=campaignType:COUPON, ORDER_DISCOUNT.

Passing in no value for campaignType returns all email campaign types.

status returns only email campaigns that currently have the specified status. For instance, to return only active email campaigns, set q=status:ACTIVE.

marketplaceID returns only email campaigns that are addressed to the specified eBay marketplace. For instance, to retrieve all email campaigns made for the Australian marketplace only, set q=campaignType:marketplaceID:EBAY_AU.

Putting the above together, if a seller wanted to return all active Coupon and Order discount email campaigns for the Australian marketplace, the request would look like the following:

GET https://api.ebay.com/sell/marketing/v1/email_campaign?q=campaignType:COUPON, ORDER_DISCOUNT;status:ACTIVE;marketplaceID:EBAY_AU

Note: leaving all parameters blank will return all of a user's email campaigns.

Using limit, offset, and sort to display email campaign results

Use the limit parameter to control how many results are contained in one page. The minimum value is 1 and the maximum value is 200.

Use the offset value to skip any number of results. The default value is 0, meaning that no results will be skipped. This value cannot be less than 0.

Use the sort value to select the order for returning the results. By default, results are returned in order of email campaigns ending soonest.

A seller who wants to return all active email campaigns in the order of soonest ending, skipping the first two, and displaying only 20 at a time, would create the following request:

GET https://api.ebay.com/sell/marketing/v1/email_campaign?q=status:ACTIVE;limit=20;offset=2;sort=ENDING_FIRST

Using getEmailCampaigns with other methods

The getEmailCampaigns method is often used in conjunction with other methods that require an email campaign's unique identifier as a path parameter. Such methods are getEmailCampaign, updateEmailCampaign, deleteEmailCampaign, getEmailReport, and getEmailPreview.

To retrieve the unique identifier of an email campaign, call getEmailCampaigns.

Use the emailCampaignId value of the campaign to update, view, or delete as the email_campaign_id path parameter in the appropriate method.

To retrieve a single email campaign, call getEmailCampaign, passing the unique identifier of the email campaign into the email_campaign_id path parameter as described directly above.

Email campaign previews

The getEmailPreview generates a preview of an email campaign.

This call requires the email_campaign_id path parameter. See the Retrieving email campaigns section on obtaining the value for the email_campaign_id path parameter.

The response returns a content field that contains the raw HTML code of the email campaign that can then be rendered in other applications.

Email campaign reports

The getEmailReport method performance data on all active email campaigns for a specified time period.

This method requires the startDate and endDate path parameters and returns metrics on all of a seller's email campaigns for the period of time between the two dates.

The report contains data for the click count, open count, amount earned in sales related to email campaign clicks.

Deleting email campaigns

Sellers can delete email campaigns on an individual basis by calling the deleteEmailCampaign method and passing in the email_campaign_id path parameter.

https://strpublicapi.vip.qa.ebay.com/sell/marketing/v1/email_campaign/a9e4feeb-6945-4179-8922-32f2402a7cc79

See the Retrieving email campaigns section on obtaining the value for the email_campaign_id path parameter.