{
  "openapi": "3.1.0",
  "info": {
    "title": "DualSMS SMS activation API",
    "version": "1.0.0",
    "description": "handler_api.php-compatible API for virtual numbers and SMS codes, plus the Temp Mail API (standard mail-activation protocol) for codes by email. Full guide: https://dualsms.com/api-docs\n\nError answers:\n- BAD_KEY: The API key is missing or wrong.\n- BAD_ACTION: Unknown action.\n- BAD_SERVICE: Unknown or disabled service code.\n- BAD_COUNTRY: Unknown or disabled country.\n- BAD_STATUS: setStatus got a status it doesn't support, or the change isn't possible now (e.g. cancelling a number that already received a code).\n- NO_NUMBERS: No numbers in stock for this service and country right now.\n- NO_BALANCE: Not enough balance for this number.\n- WRONG_MAX_PRICE: The current price is above your maxPrice.\n- NO_ACTIVATION: No activation with that id on your account.\n- EARLY_CANCEL_DENIED: Cancel isn't allowed yet (first ~2 minutes).\n- ACCOUNT_BAN: This account is suspended.\n- TOO_MANY_REQUESTS: More than 120 requests per minute (HTTP 429).\n- ERROR_SQL: Temporary server error.\n\nTemp Mail API errors ({\"status\":0,\"error\":\"…\"}):\n- Bad key: The API key is missing or wrong.\n- Account is banned: This account is suspended.\n- Too many requests: More than 120 requests per minute, counted together with the numbers API (HTTP 429) — or your previous purchase is still being processed.\n- Unknown method: The method at the end of the URL doesn't exist.\n- Not supported: getBatch, getBatches, getActivationsByBatch and requestRefund aren't available here.\n- Bad service param: service is missing, unknown or disabled.\n- Bad maxPrice param: maxPrice isn't a positive number.\n- No mails yet: No emails in stock for this service and domain right now (or temp mail is unavailable).\n- Not available at this price. Try another: The price is above your maxPrice, or it changed during the purchase. data.actual_available_price is the current price.\n- Insufficient balance: Not enough balance for this email.\n- Code has not been received yet, please try again later: No code yet (or no new code yet after setStatus 5). Not a failure.\n- Activation is already canceled: The address was cancelled or expired before a code arrived (and refunded).\n- Pass mail id: getCode was called without a mailId.\n- Bad id param: id is missing or not a number.\n- No activation found with such id: No address with that id on your account.\n- Bad status param: setStatus got a status it doesn't support.\n- Bad actual activation status: The address can't move to that status now — e.g. cancel after a code arrived (or too early), or finish twice.\n- Activation is not available to get next code: This address can't receive another code.\n- Internal server error: Temporary server error."
  },
  "servers": [
    {
      "url": "https://dualsms.com/"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "apiKey",
        "in": "query",
        "name": "api_key"
      }
    }
  },
  "tags": [
    {
      "name": "Activation API",
      "description": "Buy numbers, read codes, close activations."
    },
    {
      "name": "Utility API",
      "description": "Prices, countries and services."
    },
    {
      "name": "Temp Mail API",
      "description": "Temporary email addresses for verification codes. JSON answers: {\"status\":1,…} or {\"status\":0,\"error\":\"…\"}."
    }
  ],
  "paths": {
    "/stubs/handler_api.php?action=getNumber": {
      "get": {
        "operationId": "getNumber",
        "tags": [
          "Activation API"
        ],
        "summary": "Request a number",
        "description": "Reserves a number and charges your balance. The price is final — if no SMS arrives before the activation expires, the full amount is refunded automatically. If the cheapest server runs out mid-purchase we fail over to the next one at the same price or lower.\n\nErrors: BAD_SERVICE, BAD_COUNTRY, NO_NUMBERS, NO_BALANCE, WRONG_MAX_PRICE, BAD_KEY, TOO_MANY_REQUESTS",
        "externalDocs": {
          "url": "https://dualsms.com/api-docs#getNumber"
        },
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "getNumber"
              ]
            }
          },
          {
            "name": "service",
            "in": "query",
            "required": true,
            "description": "Service code, e.g. wa for WhatsApp. See the service codes table.",
            "schema": {
              "type": "string"
            },
            "example": "wa"
          },
          {
            "name": "country",
            "in": "query",
            "required": true,
            "description": "Country: SMS-Activate numeric id (22 = India) or ISO code (in). See the country codes table.",
            "schema": {
              "type": "string"
            },
            "example": "22"
          },
          {
            "name": "maxPrice",
            "in": "query",
            "required": false,
            "description": "Highest price you accept, in your balance currency. If the current price is higher you get WRONG_MAX_PRICE instead of a number.",
            "schema": {
              "type": "string"
            },
            "example": "15"
          },
          {
            "name": "providerIds",
            "in": "query",
            "required": false,
            "description": "Buy only on these servers, comma-separated: 1,2,3 (the numbers on the site's Server 1, Server 2… — getPricesV3 lists them with prices). The cheapest of them is used and failover stays within them; none in stock → NO_NUMBERS.",
            "schema": {
              "type": "string"
            },
            "example": "1,3"
          },
          {
            "name": "operator",
            "in": "query",
            "required": false,
            "description": "Same as providerIds (for bots that send operator). Values that aren't server numbers, like any, mean any server.",
            "schema": {
              "type": "string"
            },
            "example": "2"
          }
        ],
        "responses": {
          "200": {
            "description": "ACCESS_NUMBER:$id:$phone — Number reserved. Save $id — you need it for getStatus and setStatus.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "ACCESS_NUMBER:66f1c0a2e4b0c1a2b3c4d5e6:919810427735"
              }
            }
          },
          "429": {
            "description": "TOO_MANY_REQUESTS — more than 120 requests per minute."
          }
        }
      }
    },
    "/stubs/handler_api.php?action=getNumberV2": {
      "get": {
        "operationId": "getNumberV2",
        "tags": [
          "Activation API"
        ],
        "summary": "Request a number (JSON)",
        "description": "Identical to getNumber, but the answer is JSON and includes what you were charged and when the activation started.\n\nErrors: BAD_SERVICE, BAD_COUNTRY, NO_NUMBERS, NO_BALANCE, WRONG_MAX_PRICE, BAD_KEY",
        "externalDocs": {
          "url": "https://dualsms.com/api-docs#getNumberV2"
        },
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "getNumberV2"
              ]
            }
          },
          {
            "name": "service",
            "in": "query",
            "required": true,
            "description": "Service code.",
            "schema": {
              "type": "string"
            },
            "example": "wa"
          },
          {
            "name": "country",
            "in": "query",
            "required": true,
            "description": "Country id or ISO code.",
            "schema": {
              "type": "string"
            },
            "example": "22"
          },
          {
            "name": "maxPrice",
            "in": "query",
            "required": false,
            "description": "Highest price you accept.",
            "schema": {
              "type": "string"
            },
            "example": "15"
          },
          {
            "name": "providerIds",
            "in": "query",
            "required": false,
            "description": "Buy only on these servers, comma-separated (1,2,3).",
            "schema": {
              "type": "string"
            },
            "example": "1,3"
          },
          {
            "name": "operator",
            "in": "query",
            "required": false,
            "description": "Same as providerIds.",
            "schema": {
              "type": "string"
            },
            "example": "2"
          }
        ],
        "responses": {
          "200": {
            "description": "{\"activationId\",\"phoneNumber\",\"activationCost\",\"countryCode\",\"activationTime\"} — Number reserved.",
            "content": {
              "application/json": {
                "example": {
                  "activationId": "66f1c0a2e4b0c1a2b3c4d5e6",
                  "phoneNumber": "919810427735",
                  "activationCost": "12.00",
                  "countryCode": 22,
                  "activationTime": "2026-10-20T10:56:00.000Z"
                }
              }
            }
          },
          "429": {
            "description": "TOO_MANY_REQUESTS — more than 120 requests per minute."
          }
        }
      }
    },
    "/stubs/handler_api.php?action=setStatus": {
      "get": {
        "operationId": "setStatus",
        "tags": [
          "Activation API"
        ],
        "summary": "Change activation status",
        "description": "Moves an activation forward. Cancel (8) refunds the full price as long as no SMS has arrived; it may be refused for the first two minutes (EARLY_CANCEL_DENIED) while the provider is still delivering. Complete (6) closes the activation once you have your code.\n\nErrors: NO_ACTIVATION, BAD_STATUS, EARLY_CANCEL_DENIED, BAD_KEY",
        "externalDocs": {
          "url": "https://dualsms.com/api-docs#setStatus"
        },
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "setStatus"
              ]
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": true,
            "description": "Activation id from getNumber.",
            "schema": {
              "type": "string"
            },
            "example": "66f1c0a2e4b0c1a2b3c4d5e6"
          },
          {
            "name": "status",
            "in": "query",
            "required": true,
            "description": "1 — number is ready (SMS sent) · 3 — request another SMS on the same number · 6 — complete · 8 — cancel and refund.",
            "schema": {
              "type": "string"
            },
            "example": "6"
          }
        ],
        "responses": {
          "200": {
            "description": "ACCESS_READY — Readiness confirmed (status 1).\nACCESS_RETRY_GET — Waiting for another SMS (status 3).\nACCESS_ACTIVATION — Activation completed (status 6).\nACCESS_CANCEL — Cancelled and refunded (status 8).",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "ACCESS_ACTIVATION"
              }
            }
          },
          "429": {
            "description": "TOO_MANY_REQUESTS — more than 120 requests per minute."
          }
        }
      }
    },
    "/stubs/handler_api.php?action=getStatus": {
      "get": {
        "operationId": "getStatus",
        "tags": [
          "Activation API"
        ],
        "summary": "Get the activation status",
        "description": "Returns the current state of an activation and the code once it arrives. Poll every 3–5 seconds — or skip polling entirely and receive codes on your webhook.\n\nErrors: NO_ACTIVATION, BAD_KEY",
        "externalDocs": {
          "url": "https://dualsms.com/api-docs#getStatus"
        },
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "getStatus"
              ]
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": true,
            "description": "Activation id from getNumber.",
            "schema": {
              "type": "string"
            },
            "example": "66f1c0a2e4b0c1a2b3c4d5e6"
          }
        ],
        "responses": {
          "200": {
            "description": "STATUS_WAIT_CODE — Waiting for the SMS.\nSTATUS_WAIT_RETRY:$lastCode — Waiting for another SMS; $lastCode is the previous one.\nSTATUS_OK:$code — The code arrived.\nSTATUS_CANCEL — Cancelled or expired (and refunded if no code arrived).",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "STATUS_OK:482913"
              }
            }
          },
          "429": {
            "description": "TOO_MANY_REQUESTS — more than 120 requests per minute."
          }
        }
      }
    },
    "/stubs/handler_api.php?action=getStatusV2": {
      "get": {
        "operationId": "getStatusV2",
        "tags": [
          "Activation API"
        ],
        "summary": "Get the activation status (JSON)",
        "description": "JSON version of getStatus, including the complete SMS text and when it was received — useful when the message contains more than a numeric code.\n\nErrors: NO_ACTIVATION, STATUS_CANCEL, BAD_KEY",
        "externalDocs": {
          "url": "https://dualsms.com/api-docs#getStatusV2"
        },
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "getStatusV2"
              ]
            }
          },
          {
            "name": "id",
            "in": "query",
            "required": true,
            "description": "Activation id from getNumber.",
            "schema": {
              "type": "string"
            },
            "example": "66f1c0a2e4b0c1a2b3c4d5e6"
          }
        ],
        "responses": {
          "200": {
            "description": "{\"verificationType\",\"sms\":{\"dateTime\",\"code\",\"text\"},\"call\",\"status\"} — sms is null while waiting.",
            "content": {
              "application/json": {
                "example": {
                  "verificationType": 0,
                  "sms": {
                    "dateTime": "2026-10-20 10:56:07",
                    "code": "482913",
                    "text": "Your WhatsApp code: 482-913"
                  },
                  "call": null,
                  "status": "STATUS_OK"
                }
              }
            }
          },
          "429": {
            "description": "TOO_MANY_REQUESTS — more than 120 requests per minute."
          }
        }
      }
    },
    "/stubs/handler_api.php?action=getActiveActivations": {
      "get": {
        "operationId": "getActiveActivations",
        "tags": [
          "Activation API"
        ],
        "summary": "List active activations",
        "description": "Returns every open activation on your account — handy after a restart of your bot, to pick up where it left off.\n\nErrors: BAD_KEY",
        "externalDocs": {
          "url": "https://dualsms.com/api-docs#getActiveActivations"
        },
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "getActiveActivations"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "{\"status\":\"success\",\"activeActivations\":[…]} — activationStatus: 1 waiting · 2 code received.",
            "content": {
              "application/json": {
                "example": {
                  "status": "success",
                  "activeActivations": [
                    {
                      "activationId": "66f1c0a2e4b0c1a2b3c4d5e6",
                      "serviceCode": "wa",
                      "phoneNumber": "919810427735",
                      "activationCost": "12.00",
                      "activationStatus": "2",
                      "smsCode": [
                        "482913"
                      ],
                      "smsText": [
                        "Your WhatsApp code: 482-913"
                      ],
                      "activationTime": "2026-10-20 10:56:00",
                      "countryCode": "22"
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "TOO_MANY_REQUESTS — more than 120 requests per minute."
          }
        }
      }
    },
    "/stubs/handler_api.php?action=getBalance": {
      "get": {
        "operationId": "getBalance",
        "tags": [
          "Activation API"
        ],
        "summary": "Balance",
        "description": "The balance you can spend now, in the site currency, with two decimals. Money on hold on your account isn't included.\n\nErrors: BAD_KEY, ACCOUNT_BAN",
        "externalDocs": {
          "url": "https://dualsms.com/api-docs#getBalance"
        },
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "getBalance"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ACCESS_BALANCE:$balance — Current balance.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                },
                "example": "ACCESS_BALANCE:976.00"
              }
            }
          },
          "429": {
            "description": "TOO_MANY_REQUESTS — more than 120 requests per minute."
          }
        }
      }
    },
    "/stubs/handler_api.php?action=getPrices": {
      "get": {
        "operationId": "getPrices",
        "tags": [
          "Utility API"
        ],
        "summary": "Prices and stock",
        "description": "Your price and how many numbers are available, grouped by country id then service code. Filter with service and/or country to keep the answer small. Cached for one minute.\n\nErrors: BAD_KEY",
        "externalDocs": {
          "url": "https://dualsms.com/api-docs#getPrices"
        },
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "getPrices"
              ]
            }
          },
          {
            "name": "service",
            "in": "query",
            "required": false,
            "description": "Only this service code.",
            "schema": {
              "type": "string"
            },
            "example": "wa"
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Only this country id or ISO code.",
            "schema": {
              "type": "string"
            },
            "example": "22"
          }
        ],
        "responses": {
          "200": {
            "description": "{\"$country\":{\"$service\":{\"cost\",\"count\"}}} — cost is your price; count is available numbers.",
            "content": {
              "application/json": {
                "example": {
                  "22": {
                    "wa": {
                      "cost": 12,
                      "count": 4310
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "TOO_MANY_REQUESTS — more than 120 requests per minute."
          }
        }
      }
    },
    "/stubs/handler_api.php?action=getPricesV3": {
      "get": {
        "operationId": "getPricesV3",
        "tags": [
          "Utility API"
        ],
        "summary": "Prices per server",
        "description": "Like getPrices, but split by server: country id → service code → server number → your price, available numbers and the server's id and name. Pass the ids you want to getNumber as providerIds (or operator). Same shape as SMSBower's getPricesV3. Cached for one minute.\n\nErrors: BAD_KEY",
        "externalDocs": {
          "url": "https://dualsms.com/api-docs#getPricesV3"
        },
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "getPricesV3"
              ]
            }
          },
          {
            "name": "service",
            "in": "query",
            "required": false,
            "description": "Only this service code.",
            "schema": {
              "type": "string"
            },
            "example": "wa"
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "Only this country id or ISO code.",
            "schema": {
              "type": "string"
            },
            "example": "22"
          }
        ],
        "responses": {
          "200": {
            "description": "{\"$country\":{\"$service\":{\"$server\":{\"price\",\"count\",\"provider_id\",\"provider_name\"}}}} — price is your price on that server; count is available numbers there.",
            "content": {
              "application/json": {
                "example": {
                  "22": {
                    "wa": {
                      "1": {
                        "price": 12,
                        "count": 3100,
                        "provider_id": 1,
                        "provider_name": "Server 1"
                      },
                      "3": {
                        "price": 14.5,
                        "count": 1210,
                        "provider_id": 3,
                        "provider_name": "Server 3"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "TOO_MANY_REQUESTS — more than 120 requests per minute."
          }
        }
      }
    },
    "/stubs/handler_api.php?action=getCountries": {
      "get": {
        "operationId": "getCountries",
        "tags": [
          "Utility API"
        ],
        "summary": "List of countries",
        "description": "Every country you can buy numbers in, keyed by the id to pass as country.\n\nErrors: BAD_KEY",
        "externalDocs": {
          "url": "https://dualsms.com/api-docs#getCountries"
        },
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "getCountries"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "{\"$id\":{\"id\",\"eng\",\"iso\",\"visible\"}} — One entry per country.",
            "content": {
              "application/json": {
                "example": {
                  "6": {
                    "id": 6,
                    "eng": "Indonesia",
                    "iso": "id",
                    "visible": 1
                  },
                  "22": {
                    "id": 22,
                    "eng": "India",
                    "iso": "in",
                    "visible": 1
                  }
                }
              }
            }
          },
          "429": {
            "description": "TOO_MANY_REQUESTS — more than 120 requests per minute."
          }
        }
      }
    },
    "/stubs/handler_api.php?action=getServicesList": {
      "get": {
        "operationId": "getServicesList",
        "tags": [
          "Utility API"
        ],
        "summary": "List of services",
        "description": "Every service you can buy numbers for, with the code to pass as service.\n\nErrors: BAD_KEY",
        "externalDocs": {
          "url": "https://dualsms.com/api-docs#getServicesList"
        },
        "parameters": [
          {
            "name": "action",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "getServicesList"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "{\"status\":\"success\",\"services\":[{\"code\",\"name\"}]} — One entry per service.",
            "content": {
              "application/json": {
                "example": {
                  "status": "success",
                  "services": [
                    {
                      "code": "wa",
                      "name": "WhatsApp"
                    },
                    {
                      "code": "tg",
                      "name": "Telegram"
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "TOO_MANY_REQUESTS — more than 120 requests per minute."
          }
        }
      }
    },
    "/api/mail/getActivation": {
      "get": {
        "operationId": "mailGetActivation",
        "tags": [
          "Temp Mail API"
        ],
        "summary": "Buy an email address",
        "description": "Reserves an email address and charges your balance. If no code arrives before the address closes, it's cancelled and the full price is refunded automatically. Leave out domain to get the cheapest domain in stock. A ref parameter is accepted and ignored.\n\nErrors ({\"status\":0,\"error\":…}): Bad service param, Bad maxPrice param, No mails yet, Not available at this price. Try another, Insufficient balance, Bad key, Too many requests",
        "externalDocs": {
          "url": "https://dualsms.com/api-docs#mail-getActivation"
        },
        "parameters": [
          {
            "name": "service",
            "in": "query",
            "required": true,
            "description": "Service code, e.g. tg for Telegram — the same codes as the numbers API. See the service codes table.",
            "schema": {
              "type": "string"
            },
            "example": "tg"
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Email domain from getPriceRests, e.g. gmail.com. Without it you get the cheapest domain in stock.",
            "schema": {
              "type": "string"
            },
            "example": "gmail.com"
          },
          {
            "name": "maxPrice",
            "in": "query",
            "required": false,
            "description": "Highest price you accept, in your balance currency. If the current price is higher you get “Not available at this price. Try another” with the current price in data.actual_available_price.",
            "schema": {
              "type": "string"
            },
            "example": "200"
          }
        ],
        "responses": {
          "200": {
            "description": "{\"status\":1,\"mail\",\"mailId\"} — Address reserved. Save mailId — you need it for getCode, getStatus and setStatus.",
            "content": {
              "application/json": {
                "example": {
                  "status": 1,
                  "mail": "box1@gmail.com",
                  "mailId": 100001
                }
              }
            }
          },
          "429": {
            "description": "Too many requests — more than 120 requests per minute (shared with the numbers API)."
          }
        }
      }
    },
    "/api/mail/getCode": {
      "get": {
        "operationId": "mailGetCode",
        "tags": [
          "Temp Mail API"
        ],
        "summary": "Get the code",
        "description": "Returns the latest code that arrived on the address. Until it arrives — and while you wait for the next code after setStatus 5 — the answer is “Code has not been received yet, please try again later”. Poll every 3–5 seconds. Most emails give a short code, but some services send a verification link or a whole email instead: then code is that link, or the email's text / HTML, exactly as it arrived.\n\nErrors ({\"status\":0,\"error\":…}): Activation is already canceled, Pass mail id, No activation found with such id, Bad key, Too many requests",
        "externalDocs": {
          "url": "https://dualsms.com/api-docs#mail-getCode"
        },
        "parameters": [
          {
            "name": "mailId",
            "in": "query",
            "required": true,
            "description": "The mailId from getActivation (it may also be sent as id).",
            "schema": {
              "type": "string"
            },
            "example": "100001"
          }
        ],
        "responses": {
          "200": {
            "description": "{\"status\":1,\"code\"} — The latest code.\n{\"status\":0,\"error\":\"Code has not been received yet, please try again later\"} — No code yet — ask again in a few seconds.",
            "content": {
              "application/json": {
                "example": {
                  "status": 1,
                  "code": "123456"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests — more than 120 requests per minute (shared with the numbers API)."
          }
        }
      }
    },
    "/api/mail/getStatus": {
      "get": {
        "operationId": "mailGetStatus",
        "tags": [
          "Temp Mail API"
        ],
        "summary": "Get the status",
        "description": "The state of an address as a number (see Mail statuses), its last code, and whether you can ask for another code with setStatus 5.\n\nErrors ({\"status\":0,\"error\":…}): Bad id param, No activation found with such id, Bad key, Too many requests",
        "externalDocs": {
          "url": "https://dualsms.com/api-docs#mail-getStatus"
        },
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "description": "The mailId from getActivation (it may also be sent as mailId).",
            "schema": {
              "type": "string"
            },
            "example": "100001"
          }
        ],
        "responses": {
          "200": {
            "description": "{\"status\":1,\"data\":{\"status\",\"status_description\",\"available_to_get_next_code\",\"last_code\"}} — data.status: 1 waiting for a code · 3 code received · 5 waiting for the next code · 2 cancelled.",
            "content": {
              "application/json": {
                "example": {
                  "status": 1,
                  "data": {
                    "status": 3,
                    "status_description": "Mail has been activated",
                    "available_to_get_next_code": true,
                    "last_code": "123456"
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests — more than 120 requests per minute (shared with the numbers API)."
          }
        }
      }
    },
    "/api/mail/setStatus": {
      "get": {
        "operationId": "mailSetStatus",
        "tags": [
          "Temp Mail API"
        ],
        "summary": "Change the status",
        "description": "Cancel (2) refunds the full price — only before a code has arrived. Finish (3) closes the address once you have your code. Next code (5) keeps the same address open for another code at no extra cost.\n\nErrors ({\"status\":0,\"error\":…}): Bad status param, Bad id param, No activation found with such id, Bad actual activation status, Activation is not available to get next code, Bad key",
        "externalDocs": {
          "url": "https://dualsms.com/api-docs#mail-setStatus"
        },
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "description": "The mailId from getActivation (it may also be sent as mailId).",
            "schema": {
              "type": "string"
            },
            "example": "100001"
          },
          {
            "name": "status",
            "in": "query",
            "required": true,
            "description": "2 — cancel and refund (no code yet) · 3 — finish · 5 — wait for the next code on the same address.",
            "schema": {
              "type": "string"
            },
            "example": "3"
          }
        ],
        "responses": {
          "200": {
            "description": "{\"status\":1,\"message\":\"Success\"} — Cancelled and refunded (status 2).\n{\"status\":1,\"message\":\"Activation succeed\"} — Finished (status 3).\n{\"status\":1,\"message\":\"Wait for next code\"} — Waiting for another code (status 5).",
            "content": {
              "application/json": {
                "example": {
                  "status": 1,
                  "message": "Activation succeed"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests — more than 120 requests per minute (shared with the numbers API)."
          }
        }
      }
    },
    "/api/mail/getPriceRests": {
      "get": {
        "operationId": "mailGetPriceRests",
        "tags": [
          "Temp Mail API"
        ],
        "summary": "Prices and stock",
        "description": "Your price per email and how many are in stock, grouped by service code then email domain. Only what is in stock is listed — an empty data means nothing is on sale right now. Filter with service and/or domain to keep the answer small. Cached for 30 seconds.\n\nErrors ({\"status\":0,\"error\":…}): Bad key, Too many requests",
        "externalDocs": {
          "url": "https://dualsms.com/api-docs#mail-getPriceRests"
        },
        "parameters": [
          {
            "name": "service",
            "in": "query",
            "required": false,
            "description": "Only this service code.",
            "schema": {
              "type": "string"
            },
            "example": "tg"
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Only this email domain.",
            "schema": {
              "type": "string"
            },
            "example": "gmail.com"
          }
        ],
        "responses": {
          "200": {
            "description": "{\"status\":1,\"data\":{\"$service\":{\"$domain\":{\"price\",\"count\"}}}} — price is your price per email; count is how many are in stock.",
            "content": {
              "application/json": {
                "example": {
                  "status": 1,
                  "data": {
                    "tg": {
                      "gmail.com": {
                        "price": "162.00",
                        "count": 5678
                      },
                      "outlook.com": {
                        "price": "24.00",
                        "count": 1240
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests — more than 120 requests per minute (shared with the numbers API)."
          }
        }
      }
    },
    "/api/mail/getBalance": {
      "get": {
        "operationId": "mailGetBalance",
        "tags": [
          "Temp Mail API"
        ],
        "summary": "Balance",
        "description": "The balance you can spend now, in the site currency, with two decimals — the same wallet the numbers API uses (money on hold isn't included). An extra beyond the standard mail protocol.\n\nErrors ({\"status\":0,\"error\":…}): Bad key, Account is banned",
        "externalDocs": {
          "url": "https://dualsms.com/api-docs#mail-getBalance"
        },
        "parameters": [],
        "responses": {
          "200": {
            "description": "{\"status\":1,\"balance\"} — Current balance.",
            "content": {
              "application/json": {
                "example": {
                  "status": 1,
                  "balance": "976.00"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests — more than 120 requests per minute (shared with the numbers API)."
          }
        }
      }
    }
  },
  "webhooks": {
    "sms.received": {
      "post": {
        "summary": "sms.received event",
        "description": "POSTed to the webhook URL from Settings → API. Signed with X-Webhook-Signature: t=<unix>,v1=HMAC-SHA256(secret, `${t}.${body}`).",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "id": "6714f2c9a1b2c3d4e5f60718",
                "event": "sms.received",
                "createdAt": "2026-10-20T10:56:07.412Z",
                "data": {
                  "activationId": "66f1c0a2e4b0c1a2b3c4d5e6",
                  "service": "wa",
                  "serviceName": "WhatsApp",
                  "country": 22,
                  "countryName": "India",
                  "phone": "919810427735",
                  "price": 12,
                  "status": "received",
                  "code": "482913",
                  "text": "Your WhatsApp code: 482-913",
                  "receivedAt": "2026-10-20T10:56:07.000Z"
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx within 5 seconds acknowledges the event."
          }
        }
      }
    },
    "activation.status": {
      "post": {
        "summary": "activation.status event",
        "description": "POSTed to the webhook URL from Settings → API. Signed with X-Webhook-Signature: t=<unix>,v1=HMAC-SHA256(secret, `${t}.${body}`).",
        "requestBody": {
          "content": {
            "application/json": {
              "example": {
                "id": "6714f31ea1b2c3d4e5f60719",
                "event": "activation.status",
                "createdAt": "2026-10-20T11:16:00.204Z",
                "data": {
                  "activationId": "66f1c0a2e4b0c1a2b3c4d5e6",
                  "service": "wa",
                  "serviceName": "WhatsApp",
                  "country": 22,
                  "countryName": "India",
                  "phone": "919810427735",
                  "price": 12,
                  "status": "expired",
                  "previousStatus": "waiting",
                  "refunded": true
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Any 2xx within 5 seconds acknowledges the event."
          }
        }
      }
    }
  }
}