---
title: "Replace email channel"
method: POST
path: "/api/channels/email/replace/{channel_id}"
tags: ["Email"]
---

# Replace email channel

`POST /api/channels/email/replace/{channel_id}`

## Request

- Base URL: `https://go.urbanairship.com`
- URL: `https://go.urbanairship.com/api/channels/email/replace/{channel_id}`
- Auth: one of:
  - HTTP basic
  - HTTP bearer
  - OAuth 2
    - Client credentials
    - Token URL: `http://oauth2.{domain}.com/token` scopes: `chn`
- TypeScript: <https://skmtc.dev/airship/apis/airship-api/docs/api/channels/email/replace/:channel_id/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new email channel in place of the provided channel. You may
use this endpoint to change a contact's email address. When called with
an email channel, this endpoint will:

* Register a new channel
* Associate the new email channel with the same user as the source channel
* Uninstall the source channel

## Path parameters

- `channel_id` string, required

## Request body

- EmailChannelObject: An email channel object is the object used to create channels. There are two types of emails: commercial and transactional. Commercial emails are promotional. Transactional emails are functional responses to interactions with a your app or website, like receipts, legal notices, and password reset requests. Users must explicitly opt-in to receive commercial emails; users do not need to opt-in to receive transactional emails (though they can explicitly opt-out). Each channel uses `opted_in` and `opted_out` keys for both commercial and transactional emails. The value of each key is the [date-time](/developer/rest-api/ua/introduction/#date-time-format) when the user subscribed to or unsubscribed from emails of either type — commercial or transactional. If a user has opted out of a particular email type (or the user never opted in to commercial emails), and the user is a part of your audience for a message of that type, the email designated for the opted-out user is dropped at delivery time. These values are all optional. However, an email channel with no `opted_in` or `opted_out` values can only receive transactional emails. If a channel has both opt_in and opt_out values for a particular email type, Airship respects the most recent [date-time](/developer/rest-api/ua/introduction/#date-time-format). So, if a user opted in to commercial emails after previously opting out, that user can receive commercial emails from you even though that user's channel possesses both `commercial_opted_in` and `commercial_opted_out` values; if the opt-in date is prior to the opt-out date, the user will not receive commercial emails from you. Providing both opt-in and opt-out values for commercial email, transactional email, open tracking, or click tracking in a single request is considered invalid.
  - `attributes` object: An optional object containing the customer-provided attributes associated with the email.
  - `channel` object, required
    - `address` string, required: The email address being registered.
    - `click_tracking_opted_in` string, date-time: The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when a user opted in to click tracking.
    - `click_tracking_opted_out` string, date-time: The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when a user opted out of click tracking.
    - `commercial_opted_in` string, date-time: The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when a user gave explicit permission to receive commercial emails.
    - `commercial_opted_out` string, date-time: The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when a user explicitly denied permission to receive commercial emails.
    - `locale_country` string: The device property tag related to locale country setting.
    - `locale_language` string: The device property tag related to locale language setting.
    - `open_tracking_opted_in` string, date-time: The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when a user opted in to open tracking.
    - `open_tracking_opted_out` string, date-time: The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when a user opted out of open tracking.
    - `suppression_state` 'spam_complaint' | 'commercial_spam_complaint' | 'bounce' | 'imported' | 'carrier_deactivation': The reason an email or SMS channel is suppressed. Suppressed channels don't receive messages. - `spam_complaint`, `commercial_spam_complaint`, `bounce`, and `imported` are email only. See [Email Bounce Handling and Suppression](/developer/api-integrations/email/bounce-handling/). - `carrier_deactivation` is SMS only. It is set when Airship's nightly carrier deactivation scan suppresses the channel. See [Suppression](/developer/api-integrations/sms/opt-in-out-handling#suppression) in *SMS Opt-In/Out Handling*.
    - `timezone` string: The device property tag related to time zone setting.
    - `transactional_opted_in` string, date-time: The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when a user gave explicit permission to receive transactional emails. Users do not need to opt-in to receive transactional emails unless they have previously opted out.
    - `transactional_opted_out` string, date-time: The [date-time](/developer/rest-api/ua/introduction/#date-time-format) when a user explicitly denied permission to receive transactional emails.
    - `type` 'email', required: The type of channel you are registering.
  - `opt_in_mode` 'classic' | 'double': The opt-in mode for registering the channel. `classic` is the default when unspecified, `double` creates a `double_opt_in` event.
  - `properties` object: An object containing event properties. You can use these properties to filter the double opt-in event and reference them in your message content by using handlebars. Items in the `properties` object are limited to a 255-character maximum string length.
  - `tag_operations` TagGroupObject: Tag groups appear within the `tags` object for a named user or the `tag_groups` object for a channel. `ua_` is a reserved prefix for Airship-specific tag groups. See [Device property tags](/reference/data-collection/device-property-tags/).

## Response `201`

The operation was successful.

## Other responses

- `400`: There was a parsing or validation error in the request. Bad Request errors typically include `path` and `location` in the response to help you find the cause of the error.
- `401`: Authentication information (the app key and secret or bearer token) was either incorrect or missing.

## Changes

- **2025-11-19** `43eb86d7e2d0`: 1 warning, 1 info
  - removed the request property `tags`
  - added the new optional request property `tag_operations`
  - …this revision’s changelog is incomplete

[Operation history](https://skmtc.dev/airship/apis/airship-api/changes/api/channels/email/replace/:channel_id/post.md)

---

[API](https://skmtc.dev/airship/apis/airship-api.md) - [All operations](https://skmtc.dev/airship/apis/airship-api/llms.txt) - [OpenAPI document](https://skmtc.dev/airship/apis/airship-api/revisions/bd6ab947117a?raw)