Documentation

Update Alias

Update an existing email alias for a domain.

PUT /domains/:domain_name/aliases/:alias_id
Example: /domains/example.com/aliases/alias_01k3tgwp77fgqtt8fb1xvkzw6r

Path Parameters

domain_name string required

The domain name for which to update the alias.

alias_id string required

The ID of the alias to update.

Body Parameters

match string

The pattern to match email addresses. Can be a simple word, regular expression (wrapped in /), or * for catch-all.

actions array

Array of actions to perform when an email matches this alias.
You can have multiple actions of different types for a single alias.

type string required

The type of action to perform.

Possible values: "forward" | "webhook" | "passthrough"
See Action Types for information on the parameters for each action type.

Example:

curl -X PUT https://api.mailcast.io/v1/domains/:domain_name/aliases/:alias_id \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d $'{
  "match": "webhook",
  "actions": [
    {
      "type": "webhook",
      "endpoint": "https://example.com/webhook",
      "method": "post",
      "format": "multipart",
      "fields": ["from", "to", "subject", "text_part", "html_part", "attachments"],
      "headers": [
        {
          "name": "X-Custom-Header",
          "value": "Custom Value"
        }
      ],
      "extra_fields": [
        {
          "name": "custom_field",
          "value": "Custom Value"
        }
      ]
    }
  ]
}'
Response 200
{
  "id": "alias_01h2x3y4z5",
  "match": "webhook",
  "state": "active",
  "actions": [
    {
      "type": "webhook",
      "endpoint": "https://example.com/webhook",
      "method": "post",
      "format": "multipart",
      "fields": ["from", "to", "subject", "text_part", "html_part", "attachments"],
      "headers": [
        {
          "name": "X-Custom-Header",
          "value": "Custom Value"
        }
      ],
      "extra_fields": [
        {
          "name": "custom_field",
          "value": "Custom Value"
        }
      ],
      "state": "active"
    }
  ],
  "created_at": "2025-08-29T12:00:00Z",
  "updated_at": "2025-08-29T13:30:00Z"
}