post
/users/@me/email-change/applyApply a verified email change
Applies a previously verified email_token to the current user's account. Requires sudo mode verification (password for users without MFA, MFA proof for users with MFA). Returns the updated private user object. This is a dedicated alternative to PATCH /users/@me that cannot accidentally drag in unrelated profile edits.
apply_email_change
Request body
application/json
json
{
"type": "object",
"properties": {
"email_token": {
"type": "string",
"description": "Email change token returned from verify-new"
},
"password": {
"$ref": "#/components/schemas/PasswordType"
},
"mfa_method": {
"type": "string",
"enum": [
"totp",
"webauthn"
],
"x-enumNames": [
"TOTP",
"WebAuthn"
],
"x-enumDescriptions": [
"Time-based one-time password authentication via authenticator app",
"Security key or biometric authentication"
],
"description": "MFA method to use for verification"
},
"mfa_code": {
"type": "string",
"description": "MFA verification code from an authenticator app"
},
"webauthn_response": {
"type": "object",
"description": "WebAuthn authentication response"
},
"webauthn_challenge": {
"type": "string",
"description": "WebAuthn challenge string"
}
},
"required": [
"email_token"
]
}Responses
200
Success
json
{
"type": "object",
"properties": {
"id": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)$",
"description": "The unique identifier (snowflake) for this user"
},
"username": {
"type": "string",
"description": "The username of the user, not unique across the platform"
},
"discriminator": {
"type": "string",
"description": "The four-digit discriminator tag of the user"
},
"global_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The display name of the user, if set"
},
"avatar": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The hash of the user avatar image"
},
"avatar_color": {
"anyOf": [
{
"$ref": "#/components/schemas/Int32Type"
},
{
"type": "null"
}
],
"description": "The dominant avatar color of the user as an integer"
},
"bot": {
"type": "boolean",
"description": "Whether the user is a bot account"
},
"system": {
"type": "boolean",
"description": "Whether the user is an official system user"
},
"flags": {
"$ref": "#/components/schemas/PublicUserFlags"
},
"mention_flags": {
"$ref": "#/components/schemas/MentionReplyPreferences",
"description": "The user's account-wide reply mention preference"
},
"is_staff": {
"type": "boolean",
"description": "Whether the user has staff permissions"
},
"acls": {
"type": "array",
"items": {
"type": "string"
},
"description": "Access control list entries for the user"
},
"traits": {
"type": "array",
"items": {
"type": "string"
},
"description": "Special traits assigned to the user account"
},
"email": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The email address associated with the account"
},
"email_bounced": {
"type": "boolean",
"description": "Whether the current email address is marked as bounced by the mail provider"
},
"phone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Always null. Retained for old-client backward compatibility — phone numbers are no longer stored on the user record."
},
"has_verified_phone": {
"type": "boolean",
"description": "Whether this account has completed phone verification"
},
"bio": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The user biography text"
},
"pronouns": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The preferred pronouns of the user"
},
"accent_color": {
"anyOf": [
{
"$ref": "#/components/schemas/Int32Type"
},
{
"type": "null"
}
],
"description": "The user-selected accent color as an integer"
},
"timezone": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The IANA timezone identifier saved by the user. Omitted unless the user has staff access."
},
"timezone_privacy_flags": {
"$ref": "#/components/schemas/ProfileFieldPrivacyFlags"
},
"banner": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The hash of the user profile banner image"
},
"banner_color": {
"anyOf": [
{
"$ref": "#/components/schemas/Int32Type"
},
{
"type": "null"
}
],
"description": "The default banner color if no custom banner is set"
},
"mfa_enabled": {
"type": "boolean",
"description": "Whether multi-factor authentication is enabled"
},
"authenticator_types": {
"type": "array",
"items": {
"$ref": "#/components/schemas/UserAuthenticatorTypes"
},
"description": "The types of authenticators configured for MFA"
},
"verified": {
"type": "boolean",
"description": "Whether the email address has been verified"
},
"premium_type": {
"anyOf": [
{
"$ref": "#/components/schemas/UserPremiumTypes",
"description": "The type of premium subscription"
},
{
"type": "null"
}
]
},
"premium_since": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO8601 timestamp of when premium was first activated"
},
"premium_until": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO8601 timestamp of when premium access ends, including stacked gift time"
},
"premium_will_cancel": {
"type": "boolean",
"description": "Whether premium is set to cancel at the end of the billing period"
},
"premium_billing_cycle": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "The billing cycle for the premium subscription"
},
"premium_lifetime_sequence": {
"anyOf": [
{
"$ref": "#/components/schemas/Int32Type"
},
{
"type": "null"
}
],
"description": "The sequence number for lifetime premium subscribers"
},
"premium_grace_ends_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO8601 timestamp at which the post-cancel grace period ends. Set when the subscription is fully canceled in Stripe; perks remain active and the original premium_since is restored on resubscribe until this timestamp passes. Null when not in grace."
},
"premium_discriminator": {
"type": "boolean",
"description": "Whether the user selected a premium-only discriminator that will be rerolled when non-lifetime premium access ends"
},
"premium_badge_hidden": {
"type": "boolean",
"description": "Whether the premium badge is hidden on the profile"
},
"premium_badge_masked": {
"type": "boolean",
"description": "Whether the premium badge shows a masked appearance"
},
"premium_badge_timestamp_hidden": {
"type": "boolean",
"description": "Whether the premium start timestamp is hidden"
},
"premium_badge_sequence_hidden": {
"type": "boolean",
"description": "Whether the lifetime sequence number is hidden"
},
"premium_purchase_disabled": {
"type": "boolean",
"description": "Whether premium purchases are disabled for this account"
},
"premium_enabled_override": {
"type": "boolean",
"description": "Whether premium features are enabled via override"
},
"premium_perks_disabled": {
"type": "boolean",
"description": "Whether premium perks are temporarily disabled for this account"
},
"force_inbound_phone_verification": {
"type": "boolean",
"description": "Whether this account is forced through the inbound (expensive-destination) phone verification flow regardless of prefix, for debugging"
},
"password_last_changed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO8601 timestamp of the last password change"
},
"last_voice_activity_sharing_change_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO8601 timestamp of the last bulk voice-activity-sharing change. Drives the 24-hour cooldown for re-toggling the Active Now sharing default."
},
"required_actions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Actions the user must complete before full access"
},
"nsfw_allowed": {
"type": "boolean",
"description": "Whether the user is allowed to view NSFW content"
},
"has_dismissed_premium_onboarding": {
"type": "boolean",
"description": "Whether the user has dismissed the premium onboarding flow"
},
"has_ever_purchased": {
"type": "boolean",
"description": "Whether the user has ever made a purchase"
},
"has_unread_gift_inventory": {
"type": "boolean",
"description": "Whether there are unread items in the gift inventory"
},
"unread_gift_inventory_count": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647,
"format": "int32",
"description": "The number of unread gift inventory items"
},
"pending_bulk_message_deletion": {
"anyOf": [
{
"type": "object",
"properties": {
"scheduled_at": {
"type": "string",
"description": "ISO8601 timestamp of when the deletion was scheduled"
},
"channel_count": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647,
"format": "int32",
"description": "The number of channels with messages to delete"
},
"message_count": {
"type": "integer",
"minimum": 0,
"maximum": 2147483647,
"format": "int32",
"description": "The total number of messages to delete"
}
},
"required": [
"scheduled_at",
"channel_count",
"message_count"
]
},
{
"type": "null"
}
],
"description": "Information about a pending bulk message deletion request. Only populated when the legacy delayed-deletion flow is in progress; the new immediate-deletion flow does not surface a pending state here."
},
"age_verified_adult": {
"type": "boolean",
"description": "Whether the user has verified their age as an adult via credit card verification"
},
"terms_agreed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO8601 timestamp of when the user last agreed to the terms of service"
},
"privacy_agreed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "ISO8601 timestamp of when the user last agreed to the privacy policy"
}
},
"required": [
"id",
"username",
"discriminator",
"global_name",
"avatar",
"avatar_color",
"flags",
"is_staff",
"acls",
"traits",
"email",
"has_verified_phone",
"bio",
"pronouns",
"accent_color",
"banner",
"banner_color",
"mfa_enabled",
"verified",
"premium_type",
"premium_since",
"premium_until",
"premium_will_cancel",
"premium_billing_cycle",
"premium_lifetime_sequence",
"premium_grace_ends_at",
"premium_discriminator",
"premium_badge_hidden",
"premium_badge_masked",
"premium_badge_timestamp_hidden",
"premium_badge_sequence_hidden",
"premium_purchase_disabled",
"premium_enabled_override",
"premium_perks_disabled",
"password_last_changed_at",
"last_voice_activity_sharing_change_at",
"required_actions",
"nsfw_allowed",
"has_dismissed_premium_onboarding",
"has_ever_purchased",
"has_unread_gift_inventory",
"unread_gift_inventory_count",
"pending_bulk_message_deletion",
"terms_agreed_at",
"privacy_agreed_at"
]
}400
Bad Request - The request was malformed or contained invalid data
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}401
Unauthorized - Authentication is required or the token is invalid
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}403
Forbidden - You do not have permission to perform this action
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}429
Too Many Requests - You are being rate limited
json
{
"type": "object",
"properties": {
"code": {
"type": "string",
"enum": [
"RATE_LIMITED"
]
},
"message": {
"type": "string"
},
"retry_after": {
"type": "number",
"description": "Seconds to wait before retrying"
},
"global": {
"type": "boolean",
"description": "Whether this is a global rate limit"
}
},
"required": [
"code",
"message",
"retry_after"
]
}500
Internal Server Error - An unexpected error occurred
json
{
"type": "object",
"properties": {
"code": {
"$ref": "#/components/schemas/APIErrorCode"
},
"message": {
"type": "string",
"description": "Human-readable error message"
},
"errors": {
"type": "array",
"description": "Field-specific validation errors",
"items": {
"$ref": "#/components/schemas/ValidationErrorItem"
}
}
},
"required": [
"code",
"message"
]
}