Shield Aliases API

Create and manage masked email addresses with Postscale Shield. The Shield endpoints use the shared shield.postscale.io domain; use the generic aliases API for masked addresses on a verified customer-owned domain.

Active masked addresses on shared and customer-owned domains consume one organization-wide plan allowance. Disabled masked addresses remain stored but do not consume the allowance.

Create Shield Alias

POST /v1/shield/aliases

Create a new masked email alias that forwards to one or more real addresses.

Request Body

Example Request

curl -X POST https://api.postscale.io/v1/shield/aliases \
  -H "Authorization: Bearer ps_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "forward_to": ["jane@example.com"],
    "description": "Shopping sites"
  }'

Response

{
  "alias": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "org_id": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
    "domain_id": "92095226-b022-419c-b8bd-dd88b09cc052",
    "address": "xk7m9p",
    "domain": "shield.postscale.io",
    "forward_to": ["jane@example.com"],
    "action": "forward",
    "is_masked": true,
    "masked_description": "Shopping sites",
    "emails_received": 0,
    "active": true,
    "created_at": "2026-01-18T10:30:00Z",
    "updated_at": "2026-01-18T10:30:00Z"
  }
}

The full email address for this alias is xk7m9p@shield.postscale.io.

List Shield Aliases

GET /v1/shield/aliases

Retrieve a paginated list of Shield aliases for your organization.

Query Parameters

Example Request

curl -X GET "https://api.postscale.io/v1/shield/aliases?limit=50" \
  -H "Authorization: Bearer ps_live_your_api_key"

Response

{
  "aliases": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "address": "xk7m9p",
      "domain": "shield.postscale.io",
      "forward_to": ["jane@example.com"],
      "action": "forward",
      "is_masked": true,
      "masked_description": "Shopping sites",
      "emails_received": 42,
      "active": true,
      "created_at": "2026-01-18T10:30:00Z",
      "updated_at": "2026-01-18T10:30:00Z"
    }
  ],
  "total": 15,
  "limit": 50,
  "offset": 0,
  "active_masked_aliases": 23,
  "max_masked_aliases": 50,
  "max_shield_aliases": 50
}

total is the number of shared-domain Shield aliases, including disabled aliases. active_masked_aliases is the organization-wide usage across shared and customer-owned domains. max_shield_aliases is a deprecated compatibility alias for max_masked_aliases.

Get Shield Alias

GET /v1/shield/aliases/:id

Retrieve details for a specific Shield alias.

Example Request

curl -X GET https://api.postscale.io/v1/shield/aliases/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer ps_live_your_api_key"

Response

{
  "alias": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "address": "xk7m9p",
    "domain": "shield.postscale.io",
    "forward_to": ["jane@example.com"],
    "action": "forward",
    "is_masked": true,
    "masked_description": "Shopping sites",
    "emails_received": 42,
    "active": true,
    "created_at": "2026-01-18T10:30:00Z",
    "updated_at": "2026-01-18T10:30:00Z"
  }
}

Update Shield Alias

PUT /v1/shield/aliases/:id

Update an existing Shield alias.

Request Body

Example: Disable Alias

curl -X PUT https://api.postscale.io/v1/shield/aliases/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer ps_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "active": false
  }'

Response

{
  "alias": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "address": "xk7m9p",
    "domain": "shield.postscale.io",
    "forward_to": ["jane@example.com"],
    "is_masked": true,
    "active": false,
    "updated_at": "2026-01-18T12:00:00Z"
  }
}

Delete Shield Alias

DELETE /v1/shield/aliases/:id

Permanently delete a Shield alias.

Example Request

curl -X DELETE https://api.postscale.io/v1/shield/aliases/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer ps_live_your_api_key"

Response

{
  "status": "deleted"
}

Active Masked Address Limits

Only active masked addresses count toward the allowance. The same allowance covers aliases on shield.postscale.io and customer-owned domains.

Need more? Contact us for higher alias limits and volume pricing.

Reply Handling

Shield aliases support bidirectional communication. When an email is forwarded to you, the Reply-To header is rewritten to a reply address (r-{token}@shield.postscale.io). When you reply, it's automatically sent from the masked alias address, keeping your real email private.

Reply tokens expire after 90 days.