Email accounts

Embed
Preview of the card
<a href="https://numestri.com/docs/ref-email-accounts"><img src="https://numestri.com/docs/_api/public/orgs/25229885-9620-4c08-bd2e-a0d0d74ac8b6/spaces/ef21e0c3-966d-4b03-b6d2-e66d449835d4/pages/ac55017c-40da-4e98-9477-27675ae4f67c/social-card.svg?v=3e7ae33eec8b" alt="Email accounts" width="600" height="315"></a>
GEThttps://numestri.com/api/v1/email/products
Email products on sale

Every mailbox product on sale, cheapest first, priced per account. Prices are exact and often a fraction of a cent: use price_micros (millionths of a dollar) for arithmetic. An order is charged price_micros x quantity, rounded up to the cent once.

No API key needed. Without one you get public list prices, rate-limited per IP address. Send your key to get the prices for your account (which can differ from the public list) and the per-account limit; an invalid key is still refused with 403.

Also accepts POST, with the same parameters in a form (application/x-www-form-urlencoded) or JSON body.

Code samples
cURL
curl -X GET "https://numestri.com/api/v1/email/products"
TypeScript
const res = await fetch('https://numestri.com/api/v1/email/products', {
  method: 'GET',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "GET",
    "https://numestri.com/api/v1/email/products",
)
data = res.json()
Go
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://numestri.com/api/v1/email/products", nil)
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}
PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://numestri.com/api/v1/email/products');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Ruby
require 'net/http'
require 'uri'

uri = URI('https://numestri.com/api/v1/email/products')
req = Net::HTTP::Get.new(uri)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body
Java
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://numestri.com/api/v1/email/products"))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 Products.
Example
{
  "success": 1,
  "data": [
    {
      "id": "outlooktrustedgraph",
      "name": "Outlook Trusted Graph",
      "price": "0.0039",
      "price_micros": 3900,
      "in_stock": true,
      "stock_level": "plenty"
    }
  ]
}
Schema
successrequired
dataEmailProduct[]required
Show child parameters
idstringrequired
What /email/purchase takes as product.
namestringrequired
pricestringrequired
Per-account price in dollars, exact to six decimals with trailing zeros removed. Often a fraction of a cent (e.g. "0.0039").
price_microsintegerrequired
The same price in millionths of a dollar. An order is charged price_micros x quantity, rounded up to the cent once.
in_stockbooleanrequired
stock_levelstringrequired
plenty | limited | none
400 A parameter (or the API key) is missing or invalid. param names it.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
403 The API key is not valid.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
429 Over the rate limit (32 requests per second per account by default). Wait Retry-After seconds.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
500 Something went wrong on our side.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
POSThttps://numestri.com/api/v1/email/purchase
Buy email accounts

Buy accounts in bulk. If fewer are available than requested you get what there is, and the difference is refunded before this responds — always compare delivered with requested.

Safe to retry: send an Idempotency-Key header (or idempotency_key parameter) and a repeat returns the accounts the first request delivered instead of buying more.

Counts towards the per-account purchase limit (60 a minute by default, shared with numbers and rentals); over it is a 429 RATE_LIMITED with Retry-After.

Also accepts GET, with the same parameters in the query string.

Parameters
Idempotency-Keystringheader
Optional. Any unique string (a UUID is ideal), up to 255 printable characters. Retrying with the same key returns the original purchase — same body, plus an Idempotent-Replayed: true header — instead of buying again, and charges nothing. A retry while the first request is still running is a 409 (param: idempotency_key); a retry after a failed purchase tries again. A key already used on a different endpoint (say, a purchase key sent to /sms/resend) is a 422. Keys are per account and do not expire. Send it as this header, or as the idempotency_key parameter (GET query string or POST body) if your client cannot set headers.
Request body application/x-www-form-urlencoded
productstringrequired
Product id from /email/products.
quantityinteger
How many, 1 to 500.
= 1
max_pricestring
Refuse (PRICE_ABOVE_MAX) above this price per account, in dollars; may be a fraction of a cent, e.g. 0.005. Anything but a positive amount is a 400 (param: max_price).
idempotency_keystring
Same as the Idempotency-Key header, for clients that cannot set headers (e.g. GET). The header wins when both are sent.
keystring
Your API key, if you send it in the body rather than a header or the query string.
{
  "product": "outlooktrustedgraph",
  "quantity": 10,
  "max_price": "0.005",
  "idempotency_key": "3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34",
  "key": "string"
}
Code samples
cURL
curl -X POST "https://numestri.com/api/v1/email/purchase" \
  -H "Idempotency-Key: <value>" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d '{"product":"outlooktrustedgraph","quantity":10,"max_price":"0.005","idempotency_key":"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34","key":"string"}'
TypeScript
const res = await fetch('https://numestri.com/api/v1/email/purchase', {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<value>',
    'Content-Type': 'application/x-www-form-urlencoded',
  },
  body: JSON.stringify({"product":"outlooktrustedgraph","quantity":10,"max_price":"0.005","idempotency_key":"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34","key":"string"}),
});
const data = await res.json();
Python
import requests

res = requests.request(
    "POST",
    "https://numestri.com/api/v1/email/purchase",
    headers={
    "Idempotency-Key": "<value>",
    "Content-Type": "application/x-www-form-urlencoded",
    },
    json={"product": "outlooktrustedgraph", "quantity": 10, "max_price": "0.005", "idempotency_key": "3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34", "key": "string"},
)
data = res.json()
Go
package main

import (
	"fmt"
	"io"
	"net/http"
	"strings"
)

func main() {
	req, _ := http.NewRequest("POST", "https://numestri.com/api/v1/email/purchase", strings.NewReader(`{"product":"outlooktrustedgraph","quantity":10,"max_price":"0.005","idempotency_key":"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34","key":"string"}`))
	req.Header.Set("Idempotency-Key", "<value>")
	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}
PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://numestri.com/api/v1/email/purchase');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Idempotency-Key: <value>', 'Content-Type: application/x-www-form-urlencoded']);
curl_setopt($ch, CURLOPT_POSTFIELDS, '{"product":"outlooktrustedgraph","quantity":10,"max_price":"0.005","idempotency_key":"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34","key":"string"}');
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Ruby
require 'net/http'
require 'uri'

uri = URI('https://numestri.com/api/v1/email/purchase')
req = Net::HTTP::Post.new(uri)
req['Idempotency-Key'] = '<value>'
req['Content-Type'] = 'application/x-www-form-urlencoded'
req.body = '{"product":"outlooktrustedgraph","quantity":10,"max_price":"0.005","idempotency_key":"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34","key":"string"}'
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body
Java
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://numestri.com/api/v1/email/purchase"))
    .header("Idempotency-Key", "<value>")
    .header("Content-Type", "application/x-www-form-urlencoded")
    .method("POST", BodyPublishers.ofString("{\"product\":\"outlooktrustedgraph\",\"quantity\":10,\"max_price\":\"0.005\",\"idempotency_key\":\"3f1c2a9e-8d4b-4c61-9a57-0b6f2e1d7c34\",\"key\":\"string\"}"))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 What was delivered and charged (or, replayed under the same Idempotency-Key, the original order, with Idempotent-Replayed: true).
Example
{
  "success": {},
  "order_id": "K2M4PQ7X",
  "product": "outlooktrustedgraph",
  "requested": 10,
  "delivered": 7,
  "unit_price": "0.0039",
  "charged": "0.03",
  "refunded": "0.01",
  "accounts": [
    {
      "email": "jane.doe4821@outlook.com",
      "password": "xQ7!pLm2rT",
      "refresh_token": "string",
      "client_id": "string"
    }
  ]
}
Schema
successrequired
order_idstringrequired
productstringrequired
requestedintegerrequired
deliveredintegerrequired
May be fewer than requested; the difference is already refunded.
unit_pricestringrequired
Per-account price in dollars, up to six decimals.
chargedstringrequired
What was finally charged, after any refund.
refundedstringrequired
What was refunded for accounts that could not be delivered.
accountsDeliveredAccount[]required
Show child parameters
emailstringrequired
passwordstringrequired
refresh_tokenstringrequired
client_idstringrequired
400 Missing product, bad quantity or bad max_price (Error), or INVALID_QUANTITY (over 500), UNKNOWN_PRODUCT, PRICE_ABOVE_MAX (EmailFailure).
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Error
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
EmailFailure
successrequired
messagestringrequired
Human-readable, safe to show.
typestringrequired
OUT_OF_STOCK | BALANCE_ERROR | PRICE_NOT_FOUND | SERVICE_UNAVAILABLE | UNSUPPORTED | RATE_LIMITED | NOT_FOUND | CANCEL_TOO_EARLY | INVALID_QUANTITY | UNKNOWN_PRODUCT | UNKNOWN
codestringrequired
OUT_OF_STOCK | OPTION_GONE | PROVIDER_UNAVAILABLE | INSUFFICIENT_BALANCE | PRICE_ABOVE_MAX | INVALID_DAYS | NOT_SOLD | UNAVAILABLE | UNSUPPORTED | RATE_LIMITED | NOT_FOUND | CANCEL_TOO_EARLY | INVALID_QUANTITY | UNKNOWN_PRODUCT | UNKNOWN
{
  "success": 0,
  "message": "Those accounts are out of stock right now.",
  "type": "OUT_OF_STOCK",
  "code": "OUT_OF_STOCK"
}
402 Insufficient balance (type: BALANCE_ERROR, code: INSUFFICIENT_BALANCE).
Example
{
  "success": 0,
  "message": "Those accounts are out of stock right now.",
  "type": "OUT_OF_STOCK",
  "code": "OUT_OF_STOCK"
}
Schema
successrequired
messagestringrequired
Human-readable, safe to show.
typestringrequired
OUT_OF_STOCK | BALANCE_ERROR | PRICE_NOT_FOUND | SERVICE_UNAVAILABLE | UNSUPPORTED | RATE_LIMITED | NOT_FOUND | CANCEL_TOO_EARLY | INVALID_QUANTITY | UNKNOWN_PRODUCT | UNKNOWN
codestringrequired
OUT_OF_STOCK | OPTION_GONE | PROVIDER_UNAVAILABLE | INSUFFICIENT_BALANCE | PRICE_ABOVE_MAX | INVALID_DAYS | NOT_SOLD | UNAVAILABLE | UNSUPPORTED | RATE_LIMITED | NOT_FOUND | CANCEL_TOO_EARLY | INVALID_QUANTITY | UNKNOWN_PRODUCT | UNKNOWN
403 The API key is not valid.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
409 Out of stock or not currently available (EmailFailure), or A request with this Idempotency-Key is still in progress (Error, param: idempotency_key): retry in a few seconds.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Error
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
EmailFailure
successrequired
messagestringrequired
Human-readable, safe to show.
typestringrequired
OUT_OF_STOCK | BALANCE_ERROR | PRICE_NOT_FOUND | SERVICE_UNAVAILABLE | UNSUPPORTED | RATE_LIMITED | NOT_FOUND | CANCEL_TOO_EARLY | INVALID_QUANTITY | UNKNOWN_PRODUCT | UNKNOWN
codestringrequired
OUT_OF_STOCK | OPTION_GONE | PROVIDER_UNAVAILABLE | INSUFFICIENT_BALANCE | PRICE_ABOVE_MAX | INVALID_DAYS | NOT_SOLD | UNAVAILABLE | UNSUPPORTED | RATE_LIMITED | NOT_FOUND | CANCEL_TOO_EARLY | INVALID_QUANTITY | UNKNOWN_PRODUCT | UNKNOWN
{
  "success": 0,
  "message": "Those accounts are out of stock right now.",
  "type": "OUT_OF_STOCK",
  "code": "OUT_OF_STOCK"
}
429 Over the API rate limit (Error), the per-account purchase limit, or supply is rate-limiting (EmailFailure, code: RATE_LIMITED). Wait Retry-After seconds.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Error
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
EmailFailure
successrequired
messagestringrequired
Human-readable, safe to show.
typestringrequired
OUT_OF_STOCK | BALANCE_ERROR | PRICE_NOT_FOUND | SERVICE_UNAVAILABLE | UNSUPPORTED | RATE_LIMITED | NOT_FOUND | CANCEL_TOO_EARLY | INVALID_QUANTITY | UNKNOWN_PRODUCT | UNKNOWN
codestringrequired
OUT_OF_STOCK | OPTION_GONE | PROVIDER_UNAVAILABLE | INSUFFICIENT_BALANCE | PRICE_ABOVE_MAX | INVALID_DAYS | NOT_SOLD | UNAVAILABLE | UNSUPPORTED | RATE_LIMITED | NOT_FOUND | CANCEL_TOO_EARLY | INVALID_QUANTITY | UNKNOWN_PRODUCT | UNKNOWN
{
  "success": 0,
  "message": "Those accounts are out of stock right now.",
  "type": "OUT_OF_STOCK",
  "code": "OUT_OF_STOCK"
}
500 Something went wrong on our side.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
503 Temporarily unable to deliver accounts (type: SERVICE_UNAVAILABLE).
Example
{
  "success": 0,
  "message": "Those accounts are out of stock right now.",
  "type": "OUT_OF_STOCK",
  "code": "OUT_OF_STOCK"
}
Schema
successrequired
messagestringrequired
Human-readable, safe to show.
typestringrequired
OUT_OF_STOCK | BALANCE_ERROR | PRICE_NOT_FOUND | SERVICE_UNAVAILABLE | UNSUPPORTED | RATE_LIMITED | NOT_FOUND | CANCEL_TOO_EARLY | INVALID_QUANTITY | UNKNOWN_PRODUCT | UNKNOWN
codestringrequired
OUT_OF_STOCK | OPTION_GONE | PROVIDER_UNAVAILABLE | INSUFFICIENT_BALANCE | PRICE_ABOVE_MAX | INVALID_DAYS | NOT_SOLD | UNAVAILABLE | UNSUPPORTED | RATE_LIMITED | NOT_FOUND | CANCEL_TOO_EARLY | INVALID_QUANTITY | UNKNOWN_PRODUCT | UNKNOWN
GEThttps://numestri.com/api/v1/email/accounts
Your delivered accounts

Accounts delivered to you, with their credentials, newest first, a page at a time: limit from offset, then fetch again from next_offset until it is null. Pass order_id for one order's accounts (all of them, unpaged) plus the order itself. These do not expire and stay readable.

Also accepts POST, with the same parameters in a form (application/x-www-form-urlencoded) or JSON body.

Parameters
order_idstringquery
Limit to one order. limit and offset do not apply.
limitintegerquery
Accounts per page, 1 to 200.
= 200
offsetintegerquery
How many to skip: 0, then each response's next_offset.
= 0
Code samples
cURL
curl -X GET "https://numestri.com/api/v1/email/accounts?order_id=&limit=&offset="
TypeScript
const res = await fetch('https://numestri.com/api/v1/email/accounts?order_id=&limit=&offset=', {
  method: 'GET',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "GET",
    "https://numestri.com/api/v1/email/accounts?order_id=&limit=&offset=",
)
data = res.json()
Go
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://numestri.com/api/v1/email/accounts?order_id=&limit=&offset=", nil)
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}
PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://numestri.com/api/v1/email/accounts?order_id=&limit=&offset=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Ruby
require 'net/http'
require 'uri'

uri = URI('https://numestri.com/api/v1/email/accounts?order_id=&limit=&offset=')
req = Net::HTTP::Get.new(uri)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body
Java
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://numestri.com/api/v1/email/accounts?order_id=&limit=&offset="))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 Accounts.
Example
{
  "success": {},
  "order": {
    "order_id": "K2M4PQ7X",
    "product": "outlooktrustedgraph",
    "product_name": "Outlook Trusted Graph",
    "requested": 10,
    "delivered": 7,
    "unit_price": "0.0039",
    "unit_price_micros": 3900,
    "charged": "0.03",
    "charged_in_cents": 3,
    "refunded": "0.01",
    "refunded_in_cents": 1,
    "created_at": 1791942000000
  },
  "accounts": [
    {
      "id": "string",
      "email": "jane.doe4821@outlook.com",
      "password": "xQ7!pLm2rT",
      "refresh_token": "string",
      "client_id": "string",
      "delivered_at": 1791942000000
    }
  ],
  "limit": 100,
  "offset": 0,
  "next_offset": 100
}
Schema
successrequired
orderobject
An order, in the same field names /email/purchase answers with.
Show child parameters
order_idstringrequired
productstringrequired
product_namestringrequired
requestedintegerrequired
deliveredintegerrequired
unit_pricestringrequired
Per-account price in dollars, exact to six decimals (often under a cent).
unit_price_microsintegerrequired
The same price in millionths of a dollar.
chargedstringrequired
Charged, net of refunds.
charged_in_centsintegerrequired
The same amount in integer US cents.
refundedstringrequired
US dollars, as a fixed two-decimal string.
refunded_in_centsintegerrequired
The same amount in integer US cents.
created_atintegerrequired
Unix milliseconds.
accountsEmailAccount[]required
Show child parameters
idstringrequired
emailstringrequired
passwordstringrequired
refresh_tokenstringrequired
client_idstringrequired
delivered_atintegerrequired
Unix milliseconds.
limitinteger
Absent when order_id was given.
offsetinteger
Absent when order_id was given.
next_offsetinteger
Where the next page starts; null on the last page. Absent when order_id was given.
400 limit or offset out of range (param names which).
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
403 The API key is not valid.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
404 No such order of yours.
Example
{
  "success": 0,
  "message": "We could not find this order!"
}
Schema
successrequired
messagestringrequired
429 Over the rate limit (32 requests per second per account by default). Wait Retry-After seconds.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
500 Something went wrong on our side.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
GEThttps://numestri.com/api/v1/email/inbox
Newest message in a mailbox

The newest message in a mailbox you own. Poll it as you would poll for an SMS code; an empty mailbox answers message: null, which is not an error.

Also accepts POST, with the same parameters in a form (application/x-www-form-urlencoded) or JSON body.

Parameters
emailstringqueryrequired
The mailbox address, as delivered to you.
folderstringquery
inbox (default) or junk. Any other value reads the inbox.
inbox | junk = inbox
sinceintegerquery
Unix seconds: ignore anything older.
Code samples
cURL
curl -X GET "https://numestri.com/api/v1/email/inbox?email=&folder=&since="
TypeScript
const res = await fetch('https://numestri.com/api/v1/email/inbox?email=&folder=&since=', {
  method: 'GET',
});
const data = await res.json();
Python
import requests

res = requests.request(
    "GET",
    "https://numestri.com/api/v1/email/inbox?email=&folder=&since=",
)
data = res.json()
Go
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	req, _ := http.NewRequest("GET", "https://numestri.com/api/v1/email/inbox?email=&folder=&since=", nil)
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}
PHP
<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://numestri.com/api/v1/email/inbox?email=&folder=&since=');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
Ruby
require 'net/http'
require 'uri'

uri = URI('https://numestri.com/api/v1/email/inbox?email=&folder=&since=')
req = Net::HTTP::Get.new(uri)
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts res.body
Java
import java.net.URI;
import java.net.http.*;
import java.net.http.HttpRequest.BodyPublishers;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://numestri.com/api/v1/email/inbox?email=&folder=&since="))
    .GET()
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
Responses
200 The newest message, or null.
Example
{
  "success": 1,
  "message": {
    "from": "noreply@service.com",
    "subject": "Your verification code",
    "text": "Your code is 553311",
    "html": null,
    "received_at": 1791942000000
  }
}
Schema
successrequired
messageMailMessagerequired
Show child parameters
fromstringrequired
subjectstringrequired
textstringrequired
htmlstringrequired
received_atintegerrequired
Unix milliseconds.
400 Missing email, or this mailbox cannot be read from here (UNSUPPORTED).
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Error
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
EmailFailure
successrequired
messagestringrequired
Human-readable, safe to show.
typestringrequired
OUT_OF_STOCK | BALANCE_ERROR | PRICE_NOT_FOUND | SERVICE_UNAVAILABLE | UNSUPPORTED | RATE_LIMITED | NOT_FOUND | CANCEL_TOO_EARLY | INVALID_QUANTITY | UNKNOWN_PRODUCT | UNKNOWN
codestringrequired
OUT_OF_STOCK | OPTION_GONE | PROVIDER_UNAVAILABLE | INSUFFICIENT_BALANCE | PRICE_ABOVE_MAX | INVALID_DAYS | NOT_SOLD | UNAVAILABLE | UNSUPPORTED | RATE_LIMITED | NOT_FOUND | CANCEL_TOO_EARLY | INVALID_QUANTITY | UNKNOWN_PRODUCT | UNKNOWN
{
  "success": 0,
  "message": "Those accounts are out of stock right now.",
  "type": "OUT_OF_STOCK",
  "code": "OUT_OF_STOCK"
}
403 The API key is not valid.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
404 No mailbox with that address belongs to you.
Example
{
  "success": 0,
  "message": "We could not find this order!"
}
Schema
successrequired
messagestringrequired
409 Not currently available.
Example
{
  "success": 0,
  "message": "Those accounts are out of stock right now.",
  "type": "OUT_OF_STOCK",
  "code": "OUT_OF_STOCK"
}
Schema
successrequired
messagestringrequired
Human-readable, safe to show.
typestringrequired
OUT_OF_STOCK | BALANCE_ERROR | PRICE_NOT_FOUND | SERVICE_UNAVAILABLE | UNSUPPORTED | RATE_LIMITED | NOT_FOUND | CANCEL_TOO_EARLY | INVALID_QUANTITY | UNKNOWN_PRODUCT | UNKNOWN
codestringrequired
OUT_OF_STOCK | OPTION_GONE | PROVIDER_UNAVAILABLE | INSUFFICIENT_BALANCE | PRICE_ABOVE_MAX | INVALID_DAYS | NOT_SOLD | UNAVAILABLE | UNSUPPORTED | RATE_LIMITED | NOT_FOUND | CANCEL_TOO_EARLY | INVALID_QUANTITY | UNKNOWN_PRODUCT | UNKNOWN
429 Over the rate limit (32 requests per second per account by default). Wait Retry-After seconds.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
500 Something went wrong on our side.
Example
{
  "success": 0,
  "errors": [
    {
      "message": "You are missing a required parameter for this request.",
      "param": "country",
      "description": "Country code from /api/v1/catalog/platforms/{platform}/countries, e.g. US"
    }
  ]
}
Schema
successrequired
errorsobject[]required
Show child parameters
messagestringrequired
paramstring
The parameter at fault, when there is one.
descriptionstring
What the parameter should contain.
503 Temporarily unavailable.
Example
{
  "success": 0,
  "message": "Those accounts are out of stock right now.",
  "type": "OUT_OF_STOCK",
  "code": "OUT_OF_STOCK"
}
Schema
successrequired
messagestringrequired
Human-readable, safe to show.
typestringrequired
OUT_OF_STOCK | BALANCE_ERROR | PRICE_NOT_FOUND | SERVICE_UNAVAILABLE | UNSUPPORTED | RATE_LIMITED | NOT_FOUND | CANCEL_TOO_EARLY | INVALID_QUANTITY | UNKNOWN_PRODUCT | UNKNOWN
codestringrequired
OUT_OF_STOCK | OPTION_GONE | PROVIDER_UNAVAILABLE | INSUFFICIENT_BALANCE | PRICE_ABOVE_MAX | INVALID_DAYS | NOT_SOLD | UNAVAILABLE | UNSUPPORTED | RATE_LIMITED | NOT_FOUND | CANCEL_TOO_EARLY | INVALID_QUANTITY | UNKNOWN_PRODUCT | UNKNOWN
Updated