Create Alias

Create a new email alias for a domain. An alias defines how emails sent to a specific address pattern should be processed.

POST /domains/:domain_name/aliases

Example: /domains/example.com/aliases

Create a new email alias for the specified domain.

Description

This endpoint creates a new email alias that matches incoming emails based on the match pattern and processes them according to the specified actions.

Aliases can match:

Simple words: "support" matches support@domain.com
Regular expressions: "/support-[0-9]+/" matches support-123@domain.com
Catch-all: "*" matches any email address on the domain

Aliases are matched in order from simple words to regular expressions with catch-all matched if no other alias matches.

Parameters

domain_name string required

The domain name for which to create the alias.

match string required

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

actions array required

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.

Action Types

Forward Action

Forwards emails to another email address.

Parameters:

type string required

Possible values: "forward"

recipient string required

The email address to forward emails to

Example:

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

Response 201

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

Webhook Action

Sends parsed email data to a webhook endpoint.
If you need the raw email data, use the eml format or include the raw_email field in the fields parameter with a multipart format.

Parameters:

type string required

Possible values: "webhook"

endpoint url | string required

The webhook URL to send data to. It must be valid URL with a path.

method string default: "post"

Possible values: "post" | "get" | "head" | "put" | "patch"

format string default: "json"

Not every format is available for every HTTP method
See Webhooks for more information.

Possible values: "json" | "urlencoded" | "multipart" | "eml"

fields array

Array of email fields to include in the webhook payload. If not provided, all fields will be included.
Some fields are not available for all formats, see Webhooks for more information.

headers array

Array of headers to include in the webhook payload.
This is a good place to handle authentication headers if you need to authorize the webhook.

name string required

The name of the header to include in the webhook payload.

value string required

The value of the header to include in the webhook payload.

extra_fields array

Array of extra fields to include in the webhook payload.

name string required

The name of the extra field to include in the webhook payload.

value string required

The value of the extra field to include in the webhook payload.

Example:

curl -X POST https://api.mailcast.io/v1/domains/:domain_name/aliases \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d $'{
  "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 201

{
  "id": "alias_01k3tgwp77fb2adqgm2pjqv360",
  "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-29T12:00:00Z"
}

Passthrough Action

Passes emails through to existing MX servers.

Parameters:

type string required

Possible values: "passthrough"

mx_servers array required

Array of MX server configurations.

host string required

The hostname of the MX server.

priority integer required

The priority of the MX server.

Example:

curl -X POST https://api.mailcast.io/v1/domains/:domain_name/aliases \
     -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "Content-Type: application/json" \
     -d $'{
  "type": "passthrough",
  "mx_servers": [
    {
      "host": "smtp.google.com",
      "priority": 10
    }
  ]
}'

Response 201

{
  "id": "alias_01k3tgwp77fs3ttvsg2ja2r256",
  "match": "passthrough",
  "state": "active",
  "actions": [
    {
      "type": "passthrough",
      "mx_servers": [
        {
          "host": "smtp.google.com",
          "priority": 10
        }
      ],
      "state": "active"
    }
  ],
  "created_at": "2025-08-29T12:00:00Z",
  "updated_at": "2025-08-29T12:00:00Z"
}