---
title: "Create or update e-mail placement"
type: reference
method: POST
path: /rest-api/placements/update/email.do
tag: "Placements"
---

# Create or update e-mail placement

`POST https://YOUR-NETWORK-DOMAIN/rest-api/placements/update/email.do`

Creates a new e-mail placement or updates an existing one, as the console's e-mail placement editor does. If an ID is provided, the existing placement is updated; otherwise a new EMAIL_PLACEMENT is created under the zone given by zoneId, which needs the Email Placements permission. An e-mail placement is sized by an ad unit (adUnitId), which it must have. servingDomain picks the ad-serving domain its invocation code is served from, out of the domains GET placements/{placementId}/serving-domains lists; like the console's domain picker it needs the INVOCATION_CODE_DOMAIN permission, without which it is ignored. On an update, a zoneId other than the placement's own moves it to that zone, on the same or another site, and needs UPDATE on both sites; its banner links and its key stay, so its published ad tags keep working. Validation errors answer success:false with 'errors' naming the field.

## Form params

| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| `id` | integer | no | `4001` | ID of the placement to update — omit to create a new placement (then zoneId and type are required, and the caller needs INVENTORY CREATE) |
| `zoneId` | integer | no | `3001` | ID of the zone to create the placement in — required when id is omitted; on update, a zoneId other than the placement's own moves it to that zone and keeps its key (published ad tags keep working) |
| `type` | string | no | `SITE_PLACEMENT` | Placement type — required when creating and must match the endpoint: SITE_PLACEMENT for update/standard, NON_STANDARD_SITE_PLACEMENT for update/non-standard, MOBILE_SITE_PLACEMENT for update/mobile, VIDEO_PLACEMENT for update/video, APPLICATION_PLACEMENT for update/app, NATIVE_PLACEMENT for update/native, CLICK_THROUGH_PLACEMENT for update/click_through, EMAIL_PLACEMENT for update/email. On update it may be omitted; a value that differs from the stored type is rejected |
| `adUnitId` | integer | no | `5` | ID of the ad unit that sets the placement size — the preferred way to size a placement (size.adUnit is deprecated). It must be one of the ad units of the placement's type (GET /rest-api/ad-units.do); any other id is refused with 400 and nothing is changed |
| `adCategory` | string | no | `BANNER` | Ad category of an APPLICATION_PLACEMENT (a new placement starts with BANNER; omitted on update keeps the current one). applicationAdCategory sets the same value and wins when both are sent |
| `operatingSystem` | string | no | `ANDROID` | Operating system of an APPLICATION_PLACEMENT (a new placement starts with IOS; omitted on update keeps the current one). applicationOperatingSystem sets the same value and wins when both are sent |
| `actionLimitsEnabled` | boolean | no | `false` | Enable per-action conversion limits |
| `active` | boolean | no | `true` | Whether the placement is active |
| `adPosition` | string | no | `ABOVE_THE_FOLD` | Ad position on page per OpenRTB spec (ABOVE_THE_FOLD, BELOW_THE_FOLD, HEADER, FOOTER, SIDEBAR, FULL_SCREEN) |
| `ajaxCodeAdWrapper` | string | no | `FRIENDLY_FRAME` | Ad wrapper type for invocation code (WITHOUT_WRAPPER, FRIENDLY_FRAME, SANDBOXED_FRAME, NO_REDIRECT_FRAME) |
| `ajaxCodeProtocol` | string | no | `HTTPS` | Protocol for invocation code (RELATIVE, HTTPS, HTTP) |
| `allowVariableBannerSizes` | boolean | no | `false` | Allow banners of different sizes to serve in this placement |
| `alwaysRedirect` | boolean | no | `false` | Always use redirect-based ad serving instead of iframe/JavaScript |
| `applicationAdCategory` | string | no | `BANNER` | Application ad category (BANNER, INTERSTITIAL, NATIVE_AD, REWARDED_VIDEO) |
| `applicationOperatingSystem` | string | no | `ANDROID` | Target operating system for application placements (IOS, ANDROID) |
| `contentReplacementEnabled` | boolean | no | `false` | Enable content replacement mode (ad replaces page content) |
| `customOpenRtbTagId` | string | no | `custom-tag-001` | Custom OpenRTB tag ID sent in bid requests instead of the default placement key |
| `defaultCode` | string | no | `<div>No ads available</div>` | Default HTML code to display when no ad is available (passback) |
| `description` | string | no | `Top-of-page leaderboard ad slot` | Placement description |
| `disableAutoLinking` | boolean | no | `false` | Disable automatic banner-to-placement linking |
| `displayType` | string | no | `VIEW` | Display type for application placements (VIEW, ACTIVITY) |
| `domainAsDefaultChannel` | boolean | no | `false` | Use the site domain as the default channel parameter |
| `enableLinking` | boolean | no | `true` | Enable banner-to-placement linking |
| `enablePricingOverride` | boolean | no | `false` | Allow placement-level pricing to override campaign pricing |
| `enableRules` | boolean | no | `false` | Enable advanced rules engine for this placement |
| `enableTargeting` | boolean | no | `false` | Enable targeting rules for this placement |
| `fitContainer` | boolean | no | `false` | Resize the ad creative to fit the placement container |
| `name` | string | no | `Homepage Leaderboard 728x90` | Placement name |
| `nativePreferences.contextSubType` | string | no | `GENERAL` |  |
| `nativePreferences.contextType` | string | no | `CONTENT_CENTRIC` |  |
| `nativePreferences.iconSize.height` | integer | no | `90` | Height in pixels |
| `nativePreferences.iconSize.width` | integer | no | `728` | Width in pixels |
| `nativePreferences.imageSize.height` | integer | no | `90` | Height in pixels |
| `nativePreferences.imageSize.width` | integer | no | `728` | Width in pixels |
| `nativePreferences.placementType` | string | no | `IN_THE_FEED_OF_CONTENT` |  |
| `nativePreferences.requiredFields` | array<string> | no | `ICON` |  |
| `nativePreferences.videoSize.height` | integer | no | `90` | Height in pixels |
| `nativePreferences.videoSize.width` | integer | no | `728` | Width in pixels |
| `operationBetweenRuleTypes` | string | no | `AND` | Logical operator between different targeting rule types (AND, OR) |
| `piggybackStatus` | string | no | `DISABLED` | Piggyback tracking status (ENABLED, DISABLED) |
| `refreshInterval` | integer | no | `60` | Ad refresh interval in seconds (0 = no refresh) |
| `rotateInterval` | integer | no | `30` | Banner rotation interval in seconds (0 = no rotation) |
| `serverSideTrackersEnabled` | boolean | no | `false` | Whether server-side trackers fire for this placement |
| `servingDomain` | string | no | `ads.example.com` | Ad-serving domain this placement's tags and URLs are generated on — one of the domains GET /rest-api/placements/{placementId}/serving-domains.do lists; any other value is refused with 400. Needs the INVOCATION_CODE_DOMAIN permission (Set Ad-Serving Domain (Placement)), without which it is not applied |
| `showBrandedOverlay` | boolean | no | `false` | Show branded overlay on ads served in this placement |
| `size.adUnit` | string | no | `MEDIUM_RECTANGLE` | Deprecated — prefer adUnitId. Name of a predefined site ad unit; the placement gets the ad unit of that width and height |
| `size.height` | integer | no | `90` | Height in pixels |
| `size.width` | integer | no | `728` | Width in pixels |
| `thirdPartyNetworkLookupLimit` | integer | no | `5` | Maximum number of third-party network lookups for daisy chaining (0-10) |
| `videoAdMaxDuration` | integer | no | `30` | Maximum video ad duration in seconds |
| `videoAdMinDuration` | integer | no | `5` | Minimum video ad duration in seconds |
| `videoAdSkipMin` | integer | no | `5` | Minimum duration in seconds before skip button appears |
| `labels` | array<string> | no | `premium` | Label names to assign to this placement, comma-separated or repeated |
| `labelUpdateType` | string | no | `ADD` | How to handle labels: ADD (default), OVERWRITE, REMOVE, or CLEAR |

## Responses

- `200` — {success:true, id} when saved; success:false with 'errors' or 'error':'invalid_placement_type' otherwise
- `400` — servingDomain is not one of the ad-serving domains GET placements/{placementId}/serving-domains lists, or adUnitId is no ad unit of the placement's type
- `401` — Authentication error
- `403` — Creating an e-mail placement without the Email Placements permission

## Example request

```bash
curl --request POST \
  --url 'https://YOUR-NETWORK-DOMAIN/rest-api/placements/update/email.do' \
  --header 'X-Api-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'id=4001' \
  --data-urlencode 'zoneId=3001' \
  --data-urlencode 'name=Homepage Leaderboard 728x90' \
  --data-urlencode 'active=true' \
  --data-urlencode 'adCategory=BANNER'
```

Source: https://epom.com/ad-server/docs/api/placements/post-placements-update-email