Add Action

Add an action to an existing email alias.

POST /domains/:domain_name/aliases/:alias_id/actions

Example: /domains/example.com/aliases/alias_01k3tgwp77f5at1ycmwcew8me6/actions

The request body is the action payload. The alias must have at least one action; adding another action does not replace existing ones. The response is the full updated alias (including all actions) with status 201 Created.

Path Parameters

domain_name string required

The domain name that owns the alias.

alias_id string required

The ID of the alias to add the action to.

Body Parameters

The body is a single action object. See Create Alias - Action Types for parameters by action type (forward, webhook, passthrough).

forward: type, recipient
webhook: type, endpoint, method, format, and optional fields, headers, extra_fields
passthrough: type, mx_servers

Example (add a forward action):

curl -X POST https://api.mailcast.io/v1/domains/:domain_name/aliases/:alias_id/actions \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d $'{
  "type": "forward",
  "recipient": "company.owner@gmail.com"
}'

Response 201

{
  "id": "alias_01k3tgwp77f6vavfppsyyxd56c",
  "match": "support",
  "state": "active",
  "actions": [
    {
      "id": "action_01k3tgwp78e8eagk8ctzsv6f9w",
      "type": "forward",
      "state": "active",
      "recipient": "company.support@gmail.com"
    },
    {
      "id": "action_01k3tgwp79evdbjvas59m3vt4h",
      "type": "forward",
      "state": "active",
      "recipient": "company.owner@gmail.com"
    },
  ],
  "created_at": "2025-08-29T12:00:00Z",
  "updated_at": "2025-08-29T13:00:00Z"
}