Add an alias

POST/api/v1/email-accounts/{account}/aliases
Requires anorganization API keywith the scopemailboxes:write

An additional address delivering into this mailbox. Aliases cannot be used as SMTP logins; they receive only.

Parameters

NameInTypeDescription
accountrequiredpathstringThe account identifier.

Request body

  • email_account_idstringrequired

    The mailbox the alias delivers to: the same ID as in the path.

  • alias_emailstringrequired

    The extra address, on one of your domains, whose mail is delivered to this mailbox.

  • is_activeboolean

    Whether it is switched on. Defaults to true.

Request

POST/api/v1/email-accounts/{account}/aliases
curl -X POST 'https://app.mailyte.com/api/v1/email-accounts/01JBT8XQ2M9WYC3K4F6R7S8T9V/aliases' \
  -H 'Authorization: Bearer mk_live_YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "email_account_id": "01JBT8XQ2M9WYC3K4F6R7S8T9V",
    "alias_email": "sales@yourdomain.com"
  }'
The key names its own organization, so no X-Organization-ID header is needed.

Response

Success.

  • dataobject
    • objectstringmailbox_alias
    • idstring

      Unique identifier for the alias.

    • mailbox_idstring

      The mailbox this alias delivers into. Retrieve it with GET /api/v1/email-accounts/{email_account}.

    • addressstring

      The additional address. An alias **receives only** — it cannot be used as an SMTP login, and mail sent through it still leaves as the mailbox.

    • statestringactive | provisioning | failed | suspended | deleting

      The same closed set, and the same ordering, as a mailbox state, so one branch in your code handles both. Only an active alias routes mail.

    • provisioningobject

      What the mail server has done with this alias. Creation is asynchronous, so an alias exists here before it routes anything there.

      • statestringpending | provisioning | active | failed | suspended | deleting | deleted

        The alias's setup state on the mail server, with the same values as a mailbox's provisioning.state. provisioning.error names any failure.

      • errorstring

        Why provisioning failed. null unless state is failed.

      • retryableboolean

        True only while state is failed, which is the only state POST /aliases/{alias}/retry-provisioning accepts.

    • created_atstring
    • updated_atstring

Returned inside the standard envelope.

Errors

StatusWhen
401The API key is missing, unknown, revoked or expired. All four answer identically, on purpose: distinguishing them would confirm which keys exist.
403The key is valid but may not do this: it lacks the required scope, its IP allowlist does not include you, or this endpoint does not accept API keys.
404No such resource in this organization.
422The request was understood but the values were not acceptable.
429Too many requests, or the organization has spent its sending allowance. `Retry-After` says how long to wait.

Every status, with what causes it and what to do, is on the error reference.