Create an email address

POST

/domains/{domain}/email-routing/rules/

curl --request POST \
  --url https://api.nsin.ir/domains/example.com/email-routing/rules/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "local_part": "example", "action": "forward", "destination_id": 1, "name": "example", "enabled": true }'

• Production

local_part is the part before @ — ASCII letters, digits and !#$%&'*+/=?^_\{|}~.-, at most 64 characters, lowercased; a +only when the domain'ssubaddressingis on.actionisforward(with adestination_idfrom the domain owner's account) ordrop. A rule whose destination is not verified yet is stored and goes live on verification. Counts against the plan's max_email_rules. Requires records.edit`.

Authorizations

• bearerAuth
• apiKeyAuth

Parameters

Path Parameters

domain

required

string

The domain name (for example example.com) — not a numeric id.

Example

example.com

Request Body ^required

Media type application/json

object

local_part

string

action

string

Allowed values: forward drop

destination_id

Required for forward; from the domain owner’s account.

integer

name

string

<= 256 characters

enabled

Update only; create always starts enabled.

boolean

Responses

201

The created rule.

Media type application/json

object

id

integer

local_part

string

address

The full address, local_part@domain.

string

action

string

Allowed values: forward drop

destination_id

integer

nullable

destination_email

string

nullable

destination_verified

boolean

enabled

Your switch.

boolean

active

Whether the address is live right now — enabled, routing on for the domain, and (for forward) the destination verified.

boolean

name

Optional label.

string

created_at

string format: date-time

updated_at

string format: date-time

Example

{
  "action": "forward"
}

400

Invalid local part, action or destination (field names it).

Media type application/json

object

error

required

Human-readable description of what went wrong.

string

code

Machine-readable reason (hosts_not_ready, kek_unset, loop, no_mx, unverified).

string

field

The offending body field, when one applies.

string

Example

{
  "error": "read-only API key"
}

401

Missing, malformed, revoked or expired API key — or the owning account is inactive.

Media type application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

Example invalidKey

{
  "error": "invalid API key"
}

403

The key is read-only, your role lacks the permission, the domain has no active plan (402-class message with upgrade_url), the plan does not include Email Routing, or the plan’s max_email_rules is reached — the body then carries max_rules and upgrade_url.

Media type application/json

object

error

required

Human-readable description of what went wrong.

string

max_rules

integer

nullable

upgrade_url

string

Examples

Example atCap

{
  "error": "You have reached the maximum number of email addresses for this domain's plan. Upgrade the plan for this domain to add more.",
  "max_rules": 50,
  "upgrade_url": "/plans"
}

404

No such domain, or it is not visible to this account. Domains you cannot access are reported as not found rather than forbidden.

Media type application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Example

{
  "error": "read-only API key"
}

409

An address with this local part already exists (conflict: local_part).

Media type application/json

object

error

required

Human-readable description of what went wrong.

string

conflict

What conflicts (mx, spf, spf_multiple, external_dns, domain_status, not_enabled, local_part, destination).

string

records

For mx / spf_multiple — the rows in the way.

Array<object>

object

id

integer

name

string

content

string

priority

integer

record_id

For spf — the existing SPF row.

integer

content

For spf — its current value.

string

merged

For spf — what it becomes with our include merged in.

string

destination

For destination — the existing row.

object

id

integer

email

string

verified

boolean

verified_at

string format: date-time

nullable

created_at

string format: date-time

last_sent_at

When the last verification mail went out.

string format: date-time

nullable

resend_cooldown_seconds

Seconds until another verification mail may be sent; 0 when allowed now.

integer

in_use

Rules and catch-alls pointing at it.

integer

last_failure

The receiving server’s last refusal, when forwards to it are bouncing.

string

last_failure_at

string format: date-time

nullable

Example

{
  "error": "read-only API key"
}

429

The key exceeded its request budget (300 requests per minute by default).

Media type application/json

The single error shape used by every endpoint.

object

error

required

Human-readable description of what went wrong.

string

Examples

Example limited

{
  "error": "rate limit exceeded"
}