An alias is a from-address sending identity. Each alias pairs a local part with a domain — one of the managed Misar domains or a verified custom domain — and routes through an SMTP pool for deliverability isolation. You can keep transactional, newsletter, and promotional identities on different pools.

Access

Alias endpoints are account-scoped and back the MisarMail dashboard (Settings → Aliases). They authenticate with your MisarMail session — there is no separate public aliases API-key scope. Base URL: https://api.misar.io/mail.

Managed domains

Aliases on a managed Misar domain are active immediately. Aliases on a custom domain start as pending until the domain passes DNS verification.

`domainType`	Domain	Default SMTP pool
`misar_trans`	`trans.misar.io`	`transactional`
`misar_news`	`news.misar.io`	`marketing`
`misar_promo`	`promo.misar.io`	`cold`
`misar_io`	`misar.io`	`transactional`
`custom`	your verified domain (`customDomainId`)	`transactional`

Endpoints

Method	Path	Description
`GET`	`/mail/aliases`	List aliases (optional `?domainType=` / `?status=` filters)
`POST`	`/mail/aliases`	Create an alias
`PUT`	`/mail/aliases`	Update an alias (id in body)
`DELETE`	`/mail/aliases?id=<uuid>`	Soft-delete an alias

List aliases

GET/mail/aliases

List all aliases for the account (excluding deleted ones), newest first.

Query parameters

domainTypestringquery

Filter by misar_trans, misar_news, misar_promo, misar_io, or custom.

statusstringquery

Filter by alias status (e.g. active, pending, disabled).

Response fields

aliasesArray<Alias>

Each alias includes id, alias_email, alias_name, domain_type, custom_domain_id, smtp_pool (transactional | marketing | cold), smtp_pool_id, use_for_sending, use_for_receiving, is_default, status, created_at, updated_at, plus the joined custom_domain (id, domain, status) and smtp_pool_ref (id, name, pool_type, is_system, health_status, is_active).

Request

curl "https://api.misar.io/mail/aliases?domainType=misar_trans"

200 — OK

{
  "aliases": [
    {
      "id":                "550e8400-e29b-41d4-a716-446655440000",
      "alias_email":       "hello@trans.misar.io",
      "alias_name":        "Your Company",
      "domain_type":       "misar_trans",
      "custom_domain_id":  null,
      "smtp_pool":         "transactional",
      "smtp_pool_id":      null,
      "use_for_sending":   true,
      "use_for_receiving": true,
      "is_default":        true,
      "status":            "active",
      "created_at":        "2026-01-20T10:00:00Z",
      "smtp_pool_ref":     null
    }
  ]
}

Create an alias

POST/mail/aliases

Create a new alias. On a managed domain the email is localPart@<managed-domain>; for custom, supply customDomainId and the email becomes localPart@<your-domain>.

Request body

localPartstringbodyrequired

The part before the @ (1–64 chars, [a-zA-Z0-9._-]).

domainTypestringbodyrequired

One of misar_trans, misar_news, misar_promo, misar_io, custom.

customDomainIdUUIDbody

Required when domainType is custom — a verified custom domain you own.

aliasNamestringbody

Display name shown to recipients.

accountIdUUIDbody

Link the alias to a connected email account.

smtpPoolstringbody

Override the SMTP pool: transactional, marketing, or cold. Defaults from domainType.

smtpPoolIdUUIDbody

Route through a specific custom SMTP pool you own (must be active).

useForSendingbooleanbodydefault: true

Whether this alias can be used as a from-address.

useForReceivingbooleanbodydefault: true

Whether this alias receives mail.

Response fields

aliasobject

The created alias row. status is active for managed domains, pending for custom domains.

Request

curl -X POST https://api.misar.io/mail/aliases \
  -H "Content-Type: application/json" \
  -d '{
    "localPart":   "marketing",
    "domainType":  "misar_news",
    "aliasName":   "Your Company Marketing",
    "smtpPool":    "marketing"
  }'

201 — Created

{
  "alias": {
    "id":          "660e8400-e29b-41d4-a716-446655440111",
    "alias_email": "marketing@news.misar.io",
    "alias_name":  "Your Company Marketing",
    "domain_type": "misar_news",
    "smtp_pool":   "marketing",
    "is_default":  false,
    "status":      "active"
  }
}

409 — Already in use

{ "error": "marketing@news.misar.io is already in use" }

Update an alias

PUT/mail/aliases

Update an alias. The alias id is passed in the body, not the path. Setting isDefault: true unsets any other default first.

Request body

idUUIDbodyrequired

ID of the alias to update.

aliasNamestringbody

Display name.

smtpPoolstringbody

transactional, marketing, or cold.

smtpPoolIdUUID | nullbody

Reassign to a custom pool, or null to clear it.

useForSendingbooleanbody

Toggle sending.

useForReceivingbooleanbody

Toggle receiving.

isDefaultbooleanbody

Make this the default from-address.

statusstringbody

active or disabled.

Response fields

aliasobject

The updated alias.

Request

curl -X PUT https://api.misar.io/mail/aliases \
  -H "Content-Type: application/json" \
  -d '{
    "id":        "550e8400-e29b-41d4-a716-446655440000",
    "isDefault": true,
    "smtpPool":  "transactional"
  }'

200 — OK

{
  "alias": {
    "id":         "550e8400-e29b-41d4-a716-446655440000",
    "is_default": true,
    "smtp_pool":  "transactional"
  }
}

Remove an alias

DELETE/mail/aliases

Soft-delete an alias (its status becomes deleted). The default alias cannot be deleted — promote another alias to default first.

Query parameters

idUUIDqueryrequired

ID of the alias to remove.

Response fields

successboolean

true when the alias was removed.

Request

curl -X DELETE "https://api.misar.io/mail/aliases?id=660e8400-e29b-41d4-a716-446655440111"

200 — OK

{ "success": true }

Status codes

200 — OK. List, update, or delete succeeded.
201 — Created. Alias created.
400 — Bad request. Failed validation, missing/invalid alias id, missing customDomainId for a custom alias, a chosen SMTP pool that is inactive, or an attempt to delete the default alias.
401 — Unauthorized. No authenticated session.
403 — Forbidden. The alias or the selected SMTP pool does not belong to you.
404 — Not found. Alias, custom domain, or SMTP pool not found.
409 — Conflict. <email> is already in use.

SMTP pool options

Pool	Best for
`transactional`	Receipts, password resets, notifications
`marketing`	Newsletters, promotional campaigns
`cold`	Cold outreach and prospecting sends

Keeping transactional and marketing sends on separate pools protects transactional deliverability if a marketing send generates complaints.

Email Aliases

Managed domains

Endpoints

List aliases

Create an alias

Update an alias

Remove an alias

Status codes

SMTP pool options

On this page