nsindocs Search the docs⌘K
API
  1. Docs
  2. API reference
  3. Email Routing

Add a destination

posthttps://api.nsin.ir/email-routing/destinations/

Auth: Authorization: Bearer nsin_… or X-Api-Key: nsin_… — see API keys.

Adds an address to your account and emails it a verification link. Rules may point at it immediately but only fire once it is verified. Refused for an address on a domain that itself uses NSIN email routing (code: loop) or whose domain has no mail server (code: no_mx). Sends are paced: one per destination per minute, ten per account and forty per client address per hour.

Request body

Content type: application/json · required

  • emailstringrequired

    A bare ASCII address, at most 254 characters.

Responses

201Destination created; the verification mail is on its way.

Content type: application/json

  • destinationEmailDestination
    Fields
    • idinteger
    • emailstring
    • verifiedboolean

      Whether the address was confirmed through the emailed link.

    • verified_atstring | null (date-time)

      When it was confirmed.

    • created_atstring (date-time)
    • last_sent_atstring | null (date-time)

      When the last verification mail went out.

    • resend_cooldown_secondsinteger

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

    • in_useinteger

      Rules and catch-alls pointing at it.

    • last_failurestring

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

    • last_failure_atstring | null (date-time)

      When last_failure was recorded.

  • resend_cooldown_secondsinteger
json
{
  "destination": {
    "id": 0,
    "email": "string",
    "verified": true,
    "verified_at": "2026-01-01T00:00:00Z",
    "created_at": "2026-01-01T00:00:00Z",
    "last_sent_at": "2026-01-01T00:00:00Z",
    "resend_cooldown_seconds": 0,
    "in_use": 0,
    "last_failure": "string",
    "last_failure_at": "2026-01-01T00:00:00Z"
  },
  "resend_cooldown_seconds": 0
}
400Invalid address, no mail server, or a loop (code).

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

  • codestring

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

  • fieldstring

    The offending body field, when one applies.

json
{
  "error": "string",
  "code": "string",
  "field": "string"
}
401Missing, malformed, revoked or expired API key. (A valid key whose account has been deactivated gets 403 account is inactive instead.)

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "invalid API key"
}
403The account is at its destination cap (max_destinations).

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

json
{
  "error": "read-only API key"
}
409The account already has this destination (conflict: destination).

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

  • conflictstring

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

  • recordsarray of EmailConflictRecord

    For mx / spf_multiple — the rows in the way.

    Item fields
    • idinteger
    • namestring
    • contentstring
    • priorityinteger
  • record_idinteger

    For spf — the existing SPF row.

  • contentstring

    For spf — its current value.

  • mergedstring

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

  • destinationEmailDestination
    Fields
    • idinteger
    • emailstring
    • verifiedboolean

      Whether the address was confirmed through the emailed link.

    • verified_atstring | null (date-time)

      When it was confirmed.

    • created_atstring (date-time)
    • last_sent_atstring | null (date-time)

      When the last verification mail went out.

    • resend_cooldown_secondsinteger

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

    • in_useinteger

      Rules and catch-alls pointing at it.

    • last_failurestring

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

    • last_failure_atstring | null (date-time)

      When last_failure was recorded.

json
{
  "error": "string",
  "conflict": "string",
  "records": [
    {
      "id": 0,
      "name": "string",
      "content": "string",
      "priority": 0
    }
  ],
  "record_id": 0,
  "content": "string",
  "merged": "string",
  "destination": {
    "id": 0,
    "email": "string",
    "verified": true,
    "verified_at": "2026-01-01T00:00:00Z",
    "created_at": "2026-01-01T00:00:00Z",
    "last_sent_at": "2026-01-01T00:00:00Z",
    "resend_cooldown_seconds": 0,
    "in_use": 0,
    "last_failure": "string",
    "last_failure_at": "2026-01-01T00:00:00Z"
  }
}
429The per-key rate limit, a verification mail to this destination less than a minute ago (cooldownSecondsRemaining), or the account's or your address's hourly send cap.

Content type: application/json

  • errorstringrequired

    Human-readable description of what went wrong.

  • cooldownSecondsRemaininginteger
json
{
  "error": "string",
  "cooldownSecondsRemaining": 0
}

Example request

bash
curl -X POST "https://api.nsin.ir/email-routing/destinations/" \
  -H "Authorization: Bearer $NSIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "email": "string"
}'
esc