Tracking Notification Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/usps/json-schema/usps-tracking-notification-request-schema.json",
  "title": "Tracking Notification Request",
  "description": "Alows the customer to submit their e-mail address to be notified of current or future tracking activity.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/usps-tracking-openapi.yml#/components/schemas/TrackingNotificationRequest",
  "required": [
    "notifications"
  ],
  "type": "object",
  "properties": {
    "uniqueTrackingId": {
      "type": "string",
      "description": "The UniqueTrackingID is the uniqueTrackingId value located in Track/Confirm Fields API response data. Unique to each TrackID.\nInternal systems values extracted from the package tracking details.",
      "deprecated": true
    },
    "uniqueMailPieceId": {
      "type": "string",
      "description": "The uniqueMailPieceID is the uniqueMailPieceId value located in Track/Confirm Fields API response data. Unique to each TrackID. The 'expand' field in the original tracking request must be set to \"DETAIL\" in order to display this value.\nInternal systems values extracted from the package tracking details."
    },
    "approximateIntakeDate": {
      "type": "string",
      "description": "The ApproximateIntakeDate is the approximateIntakeDate value located in Track/Confirm Fields API response data. Unique to each TrackId.\nInternal systems values extracted from the package tracking details.",
      "format": "date-time",
      "deprecated": true
    },
    "mailPieceIntakeDate": {
      "type": "string",
      "description": "The mailPieceIntakeDate is the mailPieceIntakeDate value located in Track/Confirm Fields API response data. Unique to each TrackId. The 'expand' field in the original tracking request must be set to \"DETAIL\" in order to display this value.\nInternal systems values extracted from the package tracking details.",
      "format": "date-time"
    },
    "notifyEventTypes": {
      "maxItems": 7,
      "minItems": 1,
      "type": "array",
      "description": "Identifies the types of mailing events to be notified about.",
      "items": {
        "$ref": "#/$defs/MailingEventType"
      }
    },
    "firstName": {
      "maxLength": 50,
      "minLength": 0,
      "type": "string",
      "description": "The notification recipient's given name."
    },
    "lastName": {
      "maxLength": 50,
      "minLength": 0,
      "type": "string",
      "description": "The notification recipient's family name."
    },
    "notifications": {
      "maxItems": 3,
      "minItems": 1,
      "type": "array",
      "description": "Upto 3 Email addresses that notifications are to be sent.",
      "items": {
        "$ref": "#/$defs/NotificationMethod"
      }
    }
  },
  "additionalProperties": false,
  "$defs": {
    "EmailNotification": {
      "type": "object",
      "properties": {
        "email": {
          "maxLength": 50,
          "type": "string",
          "description": "E-mail address of recipient. Valid e-mail addresses must be used used for notifications via email. ",
          "format": "email"
        }
      }
    },
    "MailingEventType": {
      "title": "Mailing Event Type",
      "type": "string",
      "description": "Identifies the type of mailing events that can be notified about.",
      "enum": [
        "EMAIL_ALERT",
        "EMAIL_FUTURE_DELIVERY",
        "EMAIL_DELIVERY/NON_DELIVERY_ACTIVITY",
        "EMAIL_TODAY_DELIVERY",
        "EMAIL_AVAILABLE_FOR_PICKUP",
        "PACKAGE_ADDRESSED_TO_ME/MYUSPS_ONLY",
        "OTHER_ACTIVITY"
      ]
    },
    "NotificationMethod": {
      "type": "object",
      "oneOf": [
        {
          "$ref": "#/$defs/EmailNotification"
        },
        {
          "$ref": "#/$defs/SMSNotification"
        }
      ]
    },
    "SMSNotification": {
      "type": "object",
      "properties": {
        "cellNumber": {
          "pattern": "\\d{10}",
          "type": "string",
          "description": "The 10 digit cell number, including the area code, and with no punctuation used for notifications via text messages. This field is for future Use  \n          "
        }
      }
    }
  }
}