Email Aliases

An alias is a verified from-address identity used when sending email. Each alias maps a display name and email address to an SMTP pool (IP group). You can have multiple aliases — for example, noreply@, support@, and marketing@ — each routed through different IP pools for deliverability isolation.

Auth scope: aliases

Endpoints

| Method | Path | Description | |--------|------|-------------| | GET | /api/v1/aliases | List sending aliases | | POST | /api/v1/aliases | Create an alias | | GET | /api/v1/aliases/:id | Get a single alias | | PATCH | /api/v1/aliases/:id | Update an alias | | DELETE | /api/v1/aliases/:id | Remove an alias |

GET /api/v1/aliases

List all aliases for the authenticated account.

curl https://api.misar.io/mail/v1/aliases \
  -H "Authorization: Bearer msk_YOUR_API_KEY"

Response

{
  "success": true,
  "aliases": [
    {
      "id":          "ali_abc123",
      "email":       "[email protected]",
      "name":        "Your Company",
      "is_default":  true,
      "is_verified": true,
      "ip_pool":     "marketing",
      "created_at":  "2026-01-20T10:00:00Z"
    }
  ]
}

POST /api/v1/aliases

Create a new sending alias. The alias email must be on a verified custom domain or be a connected IMAP account.

curl -X POST https://api.misar.io/mail/v1/aliases \
  -H "Authorization: Bearer msk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email":      "[email protected]",
    "name":       "Your Company Marketing",
    "is_default": false,
    "ip_pool":    "marketing"
  }'

Request Fields

| Field | Type | Required | Notes | |-------|------|----------|-------| | email | string | ✓ | From address — must be on a verified domain | | name | string | — | Display name shown to recipients | | is_default | boolean | — | Set as default from-address (only one allowed) | | ip_pool | string | — | SMTP IP pool: transactional, marketing, newsletter |

Response

{
  "success": true,
  "alias": {
    "id":          "ali_xyz789",
    "email":       "[email protected]",
    "name":        "Your Company Marketing",
    "is_default":  false,
    "is_verified": false,
    "ip_pool":     "marketing"
  }
}

Each alias requires email verification before it can be used for sending. A verification email is sent automatically on alias creation. is_verified becomes true after the recipient clicks the link.

PATCH /api/v1/aliases/:id

Update an alias. Only name, is_default, and ip_pool can be changed after creation.

curl -X PATCH https://api.misar.io/mail/v1/aliases/ali_abc123 \
  -H "Authorization: Bearer msk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_default": true, "ip_pool": "transactional" }'

Response

{
  "success": true,
  "alias": {
    "id":         "ali_abc123",
    "email":      "[email protected]",
    "is_default": true,
    "ip_pool":    "transactional"
  }
}

DELETE /api/v1/aliases/:id

Remove an alias. Cannot delete the default alias while active campaigns reference it.

curl -X DELETE https://api.misar.io/mail/v1/aliases/ali_xyz789 \
  -H "Authorization: Bearer msk_YOUR_API_KEY"

Response

{ "success": true }

Errors

| Code | Reason | |------|--------| | 404 | Alias not found | | 409 | Alias is referenced by active campaigns — reassign first | | 403 | Cannot delete the only remaining verified alias |

IP Pool Options

| Pool | Best For | |------|----------| | transactional | Receipts, password resets, notifications | | marketing | Newsletters, promotional campaigns | | newsletter | Subscription digests, content updates |

Keeping transactional and marketing sends on separate IP pools protects your transactional deliverability if a marketing campaign generates complaints.