APIs & tools
English
English En Tiếng Việt Vi

Sonjj API

Welcome to SonjjAPI — a powerful API service providing a variety of utilities to enhance your application and streamline your workflow.

Base URL: https://app.sonjj.com

Introduction

Welcome to SonjjAPI!

This powerful API provides a variety of functions to enhance your application and streamline your workflow. Whether you're looking to:

  • Verify emails — validate deliverability and detect disposable addresses
  • Create temporary emails — Gmail, Outlook, and generic temp mail inboxes
  • Check SEO metrics — Moz, Ahrefs, backlink analysis, Google index status
  • Generate data — user profiles, phone validation, HTML-to-Markdown conversion

SonjjAPI has you covered.

Getting Started

  1. Sign up at my.sonjj.com to create your account
  2. Get your API key from the API section of your dashboard
  3. Purchase credits — see Pricing
  4. Make your first request — include your API key in the X-Api-Key header

SDKs & Tools

You can use SonjjAPI with any HTTP client:

  • cURL — quick testing from the command line
  • Python — requests or httpx
  • JavaScript / Node.js — fetch or axios
  • Postman / Insomnia — import the OpenAPI schema directly

Support

Authentication

Authentication

All API requests require authentication via an API key passed in the request header.

Getting Your API Key

  1. Log in at my.sonjj.com
  2. Navigate to the API section
  3. Copy your X-Api-Key

Using Your API Key

Include the key in every request header:

X-Api-Key: your_api_key_here

Example Requests

cURL

curl -X GET "https://app.sonjj.com/v1/check_email/validate?email=test@example.com" \
  -H "X-Api-Key: your_api_key_here"

Python

import requests

response = requests.get(
"https://app.sonjj.com/v1/check_email/validate",
params={"email": "test@example.com"},
headers={"X-Api-Key": "your_api_key_here"}
)
print(response.json())

JavaScript

const response = await fetch(
  "https://app.sonjj.com/v1/check_email/validate?email=test@example.com",
  { headers: { "X-Api-Key": "your_api_key_here" } }
);
const data = await response.json();

Error Responses

Status Meaning
401 Missing or invalid API key
403 API key valid but access denied (insufficient credits or plan)
Rate Limits

Rate Limits

SonjjAPI enforces rate limits to ensure fair usage and service stability across all users.

How It Works

Rate limiting is applied per API key and tracked at two levels:

Level Limit
Per minute Depends on your plan
Per day Depends on your plan

When you exceed the rate limit, the API returns HTTP 429 with a Retry-After header (seconds to wait) and body:

{
  "error": {
"code": 429,
"message": "Rate limit exceeded. Please wait before retrying."
  }
}

Best Practices

  • Cache responses on your side when possible
  • Implement exponential backoff on 429 responses
  • Use bulk endpoints where available instead of looping single calls
  • Monitor your credit and request usage at my.sonjj.com
Error Codes

Error Codes

SonjjAPI uses standard HTTP status codes and returns errors in a consistent JSON format.

Error Response Format

{
  "error": {
"code": 400,
"message": "Human-readable description of the error"
  }
}

HTTP Status Codes

Code Name Description
200 OK Request successful
400 Bad Request Invalid parameters or missing required fields
401 Unauthorized Missing or invalid X-Api-Key header
402 Payment Required Insufficient credits to complete the request
403 Forbidden Access denied — plan does not include this endpoint
404 Not Found The requested resource does not exist
422 Unprocessable Entity Request body is valid JSON but fails business validation
429 Too Many Requests Rate limit exceeded — slow down and retry
500 Internal Server Error Something went wrong on our end
503 Service Unavailable Server is temporarily overloaded or under maintenance

Handling Errors

Python example

import requests

response = requests.get(
"https://app.sonjj.com/v1/check_email/validate",
params={"email": "test@example.com"},
headers={"X-Api-Key": "your_api_key_here"}
)

if response.status_code == 200:
data = response.json()
elif response.status_code == 429:
print("Rate limited — implement backoff")
elif response.status_code == 402:
print("Insufficient credits")
else:
error = response.json().get("error", {})
print(f"Error {error.get('code')}: {error.get('message')}")
Market Data

Real-time and historical financial market data for Crypto, Metals, Stocks, Forex, Commodities, and Macro indicators.

Financial Intelligence

Aggregated AI context, quantitative indicators, volatility, trend detection, news, and provenance for LLM financial agents.

Email Tools

Verify email existence, account status, and disposability for generic, Gmail, and Microsoft addresses.

SEO Tools

Domain Authority (Moz), Ahrefs metrics, Google indexation, and backlink analysis for SEO workflows.

Validation Tools

Validate phone numbers (libphonenumber) and look up Bank Identification Number (BIN) data for cards.

Network & Web

IP geolocation lookup and HTML to Markdown conversion utilities.

Generators & Date

Generate realistic fake user profiles and convert solar dates to lunar (Can Chi, moon phase).

Disposable Mail

Temporary Email API is an API service that allows users to create and manage temporary emails easily and automatically. This API provides a convenient solution for receiving temporary emails without registering a real email account.

Gmail Inbox

Temporary Gmail API is an API service that allows users to use system-generated Gmail addresses to receive Opt messages, register accounts, subscribe to newsletters, and more. from other systems. We distribute this API on two platforms SonjjAPI and RapidAPI. At RapidAPI you can run API tests for free here

Outlook Inbox

Temporary Outlook API is an API service that allows users to use system-generated Outlook addresses to receive Opt messages, register accounts, subscribe to newsletters, and more. from other systems.

Schemas

Address

PropertyTypeDescription
address1* string

Primary address line.
address2 string

Secondary address line.
city string

City of the address.
state string

State of the address.
postalCode* string

Postal code of the address.
coordinates* object

Coordinates

AhrefsDataSchema

PropertyTypeDescription
page* object

PageSchema
domain* object

DomainSchema

AssetContextItem

PropertyTypeDescription
asset_id* string

Canonical asset ID
quote* object

MarketQuoteItem


Example: [object Object]
period_return_percent* number

Price return % over the selected period
high* number

Period high price
low* number

Period low price
distance_from_high_percent* number

Percentage distance from period high
volatility_percent* number

Realized historical volatility %
trend* string

Quant trend direction: up, down, sideways, insufficient_data
trend_strength* string

Quant trend strength: weak, moderate, strong
news array[object]

Up to 5 relevant news articles
macro object

Macro context facts if requested
provenance array[object]

Data section provenance metadata
warnings array[string]

Quality or data status warnings

CheckBINOut

PropertyTypeDescription
type* string

Type of card (CREDIT/DEBIT)
country* string

Country of the card issuer
brand* string

Brand of the card (e.g., VISA, MASTERCARD)
level* string

Level of the card (e.g., BUSINESS, CLASSIC)
bin* integer

Bank Identification Number (BIN)
bank* string

Name of the bank that issued the card

CheckIndexOut

PropertyTypeDescription
isIndex* boolean

True if the page is indexed, False if not
server* integer

Server response

Coordinates

PropertyTypeDescription
lat* number

Latitude of the address.
lng* number

Longitude of the address.

DateOfBirth

PropertyTypeDescription
day* integer

Day of birth.
month* integer

Month of birth.
year* integer

Year of birth.

DisposableEmailResponse

Response schema for disposable email domain check.

Returns a risk score from 0-100 indicating the likelihood that the domain is used for disposable/temporary email services.

PropertyTypeDescription
domain* string

Domain name that was checked for disposability
score* integer

Disposability risk score from 0-100 where higher scores indicate higher risk. Risk levels: 0 = Definitely legitimate (Gmail, Outlook, Yahoo, major providers), 1-30 = Low risk (corporate domains, unknown but legitimate-looking), 31-60 = Medium risk (suspicious patterns, questionable TLDs), 61-85 = High risk (catch-all domains, pattern matches), 86-100 = Very high risk (known disposable, definitely temporary)

DomainSchema

PropertyTypeDescription
backlinks* integer

Number of backlinks to the domain
refdomains* integer

Number of referring domains to the domain
traffic* number

Estimated traffic to the domain
value* integer

Monetary value of the domain
keywords* integer

Number of keywords the domain ranks for
domain_rating* number

Domain rating
ahrefs_rank* integer

Ahrefs rank of the domain

DomainsOut

Schema representing a list of domains.

PropertyTypeDescription
domains* array[string]

Domains

Email

PropertyTypeDescription
gmail* string

Gmail address.
outlook* string

Outlook address.

EmailForVerification

PropertyTypeDescription
email* string

Email address for verification.
gmail* string

Gmail address for verification.
outlook* string

Outlook address for verification.

GhostLexicalMarkdownRequest

PropertyTypeDescription
lexical string
markdown string

GhostLexicalMarkdownResponse

PropertyTypeDescription
lexical object
markdown string

GmailCheckResponse

PropertyTypeDescription
email* string

The checked Gmail address
status* string

Gmail account status


Enum: Ok, Verify, Disable, NotExist, Disable|NotExist, Error
avatar string

GmailData

PropertyTypeDescription
email* string

The email address of the Gmail user
timestamp* integer

The timestamp of the Gmail data

HTTPValidationError

PropertyTypeDescription
detail array[object]

Detail

HistoryPointItem

PropertyTypeDescription
time* integer

Unix timestamp of candle/data point
open number
high number
low number
close* number

Close price or daily rate
volume number

HtmlToMarkdownRequest

PropertyTypeDescription
html* string

HTML content to convert to Markdown (max 500KB)


Example: <h1>Hello World</h1><p>This is a <strong>test</strong></p>
sanitize boolean

HtmlToMarkdownResponse

PropertyTypeDescription
success* boolean

Request success status
markdown* string

Converted Markdown content
tokens_saved* integer

Number of tokens saved by using Markdown instead of HTML (GPT-4 estimation)

IPLookupResponse

PropertyTypeDescription
is_valid* boolean

Whether the IP was found in the database
country* string

Full country name (e.g. United States)
country_code* string

ISO 2-letter country code (e.g. US)
region* string

Region/state name (e.g. Illinois)
region_code* string

Region/state code (e.g. IL)
city* string

City name (e.g. Chicago)
zip* string

Postal/ZIP code (e.g. 60620)
lat number
lon number
timezone* string

IANA timezone (e.g. America/Chicago)
isp* string

ISP or organization name
address* string

Echo of the input IP address

InboxGmailItem

PropertyTypeDescription
mid* string

The message ID
textTo* string

The recipient email address
textFrom* string

The sender email address
textSubject* string

The subject of the email
textDate* string

The date the email was sent

InboxGmailOut

PropertyTypeDescription
messages* array[object]

The list of Gmail inbox messages

InboxItem

Schema representing an item in the inbox.

PropertyTypeDescription
mid* string

Mid
textTo* string

Textto
textFrom* string

Textfrom
textSubject* string

Textsubject
textDate* string

Textdate
attachments array[object]

InboxMessage

Represents a message in the inbox.

PropertyTypeDescription
mid* string

Unique identifier of the message
textDate* string

Date and time the message was received (ISO 8601)
textTo* string

Recipient email address
textFrom* string

Sender display name or email address
textSubject* string

Subject of the message

InboxOut

Schema representing the output of the inbox, containing multiple messages.

PropertyTypeDescription
messages* array[object]

Messages

InboxResponse

Response model for inbox messages.

PropertyTypeDescription
messages* array[object]

List of inbox messages

ListGmailOut

PropertyTypeDescription
data* array[object]

The list of Gmail data
pagination* object

Pagination

ListTempOutlookResponse

Response model for listing temporary Outlook items.

PropertyTypeDescription
data* array[object]

List of temporary Outlook items
pagination* object

Represents pagination information for list responses.

LunarDateResponse

PropertyTypeDescription
solar_date* string

Solar date used (YYYY-MM-DD)
lunar_day* integer

Lunar day (1-30)
lunar_month* integer

Lunar month (1-12)
lunar_year* integer

Lunar year
is_leap_month* boolean

Whether it is a leap month
can_chi_year* string

Heavenly Stems & Earthly Branches year (lang-dependent)
can_chi_month* string

Heavenly Stems & Earthly Branches month (lang-dependent)
can_chi_day* string

Heavenly Stems & Earthly Branches day (lang-dependent)
moon_phase_value* number

Day in moon cycle 0.0-27.99 (0=new moon, 14=full moon)
moon_phase_name* string

Moon phase name (lang-dependent)
moon_phase_emoji* string

Moon phase emoji
moon_illumination* number

Moon illumination ratio 0.0-1.0

MarketContextResponse

PropertyTypeDescription
assets* array[object]

Context grouped per requested asset
methodology* object

Deterministic quantitative metrics methodology

MarketHistoryResponse

PropertyTypeDescription
asset_id* string

Canonical asset ID
interval* string

Actual data interval
currency* string

Price currency
unit* string

Asset pricing unit
points* array[object]

Data points ordered chronologically ascending
source* string

Data provider source
source_timestamp* integer

Unix timestamp of the newest source data point
retrieved_at* integer

Unix timestamp when this API retrieved or served the data
freshness_seconds integer

Age of the newest source data point
data_status string

Data status: live, delayed, market_closed, stale, partial, unavailable
warnings array[string]

Data quality or interval warnings

MarketQuoteItem

PropertyTypeDescription
asset_id* string

Canonical asset ID (e.g. crypto:BTC-USD, metal:XAU, stock:AAPL)
name* string

Asset display name
symbol* string

Standard ticker symbol
price number
currency* string

ISO-4217 quote currency
unit* string

Pricing unit (coin, troy_ounce, barrel, share, point, etc.)
exchange string
previous_close number
change_24h number
change_24h_percent number
market_state string

Market state: open, closed, 24_7, unknown
source* string

Data provider source
source_timestamp* integer

Unix timestamp of source data
retrieved_at* integer

Unix timestamp when this API retrieved or served the data
freshness_seconds integer

Age of data in seconds at response time
data_status string

Data status: live, delayed, market_closed, stale, partial, unavailable
warnings array[string]

Data quality warnings or instrument notes

MarketQuoteResponse

PropertyTypeDescription
data* array[object]

List of market quotes matching request order

MessageGmailOut

PropertyTypeDescription
body* string

The body content of the Gmail message

MessageOut

Schema representing the output of a message.

PropertyTypeDescription
body* string

Body
attachments array[object]

MessageResponse

Response model for a single message content.

PropertyTypeDescription
body* string

HTML body content of the message

MicrosoftCheckResponse

PropertyTypeDescription
email* string

The checked Microsoft email address
status* string

Microsoft account status


Enum: Ok, Verify(sms|2fa), NotExist, Error
details object

MultiInboxOut

Schema representing the output of checking multiple inboxes at once.

PropertyTypeDescription
inboxes* object

Inboxes

NewsItem

PropertyTypeDescription
title* string

Article title
publisher* string

News publisher/source
url* string

Article URL
published_at* integer

Unix timestamp published

PageSchema

PropertyTypeDescription
backlinks* integer

Number of backlinks to the page
refdomains* integer

Number of referring domains to the page
traffic* number

Estimated traffic to the page
value* integer

Monetary value of the page
keywords* integer

Number of keywords the page ranks for
url_rating* integer

URL rating of the page
nr_words* integer

Number of words on the page

Payment

PropertyTypeDescription
bin integer

Bank Identification Number (BIN).

PhoneValidateResponse

PropertyTypeDescription
is_valid* boolean

Whether the phone number is valid
is_formatted_properly* boolean

Whether the input is already in E.164 format
country* string

Full country name (e.g. Vietnam)
location* string

Province/region associated with the number prefix
timezones* array[string]

List of timezones for the region
format_national* string

National display format (e.g. 0206 5550 100)
format_international* string

International display format (e.g. +84 206 5550 100)
format_e164* string

E.164 standard format (e.g. +842065550100)
country_code* integer

International dialing country code (e.g. 84, 1, 44)

ProvenanceItem

PropertyTypeDescription
section* string

Data section (quote, history, news)
source* string

Data source provider
timestamp* integer

Unix timestamp of source data

PublicAttachmentData

PropertyTypeDescription
id* string

Id
filename* string

Filename
size* integer

Size
mimeType* string

Mimetype

RandomGmailOut

PropertyTypeDescription
email* string

Random Gmail address
timestamp* integer

Timestamp when the email was generated
type* string

Type of email (real or alias)


Enum: real, alias

RandomOutlookResponse

Response model for a random temporary Outlook email.

PropertyTypeDescription
email* string

Random Outlook email address
timestamp* integer

Unix timestamp when the email was generated
type* string

Type of email (real or alias)


Enum: real, alias

RemoveMessageOut

PropertyTypeDescription
success* boolean

Whether the message was successfully removed
message* string

A detailed message about the operation result

SendSmtpEmailRequest

PropertyTypeDescription
smtp_host* string

SMTP server hostname (e.g. smtp.gmail.com)
smtp_port* integer

SMTP port: 465 (SSL) or 587 (STARTTLS)
smtp_user* string

SMTP login username / email
smtp_pass* string

SMTP password or App Password
use_tls boolean
from_email* string

Sender email address (From header)
from_name string
to* array[string]

List of recipient email addresses
cc array[string]
bcc array[string]
reply_to string
subject* string

Email subject line
body_text string
body_html string

SendSmtpEmailResponse

PropertyTypeDescription
success* boolean

Whether the email was sent successfully
message_id string
error_code string
error_message string

SmtpCheckCredRequest

PropertyTypeDescription
smtp_host* string

SMTP server hostname (e.g. smtp.gmail.com)
smtp_port* integer

SMTP port: 465 (SSL) or 587 (STARTTLS)
smtp_user* string

SMTP login username / email
smtp_pass* string

SMTP password or App Password
use_tls boolean

SmtpCheckCredResponse

PropertyTypeDescription
success* boolean

True if credentials are valid and login succeeded
error_code string
error_message string

TempOutlookItem

Represents a temporary item in the Outlook inbox.

PropertyTypeDescription
emails* array[string]

List of temporary email addresses
timestamp* integer

Unix timestamp of the item creation

UserGeneratorResponse

PropertyTypeDescription
name* string

Name
gender* string

Gender
dob* object

DateOfBirth
address_fake* string

Address Fake
address_real* object

Address
phone_number_fake* string

Phone Number Fake
phone_number_real* string

Phone Number Real
email_for_verification* object

EmailForVerification
email* object

Email
username* string

Username
username_short* string

Username Short
password* string

Password
payment* object

Payment

ValidationError

PropertyTypeDescription
loc* array[object]

Location
msg* string

Message
type* string

Error Type

YcheckerOut

PropertyTypeDescription
type* string

Type of email provider
disposable* string

Is the email disposable?
status* string

Status of the email
avatar string

Avatar URL only for Gmail

Pagination

PropertyTypeDescription
page* integer

The current page number
limit* integer

The number of items per page
total_count* integer

The total number of items
total_pages* integer

The total number of pages

Pagination

Represents pagination information for list responses.

PropertyTypeDescription
page* integer

Current page number
limit* integer

Number of items per page
total_count* integer

Total number of items
total_pages* integer

Total number of pages