22.Do API Documentation 22.Do API Documentation 22.Do API Documentation

Temp Mail API

API for creating temporary email accounts

Welcome to the 22.Do API documentation.

This API allows you to automate the registration process at the various sites which do require email confirmation for testing purposes.

Usage of our API for illegal activity is strictly prohibited.
It is forbidden to sell programs and/or earn from it that exclusively uses our API (for example, creating a competing temp mail client and charging for it's usage is not allowed).
Creating a mirror proxy service that explicitly utilizes our API is not allowed (for example, creating a proxy service under another domain name and then returning the results of the API).
If you are developing an wrapper and/or application that utilizes our API, you are required to explicitly mention that you are using 22.do by including a link to our main site as this would appreacited and make our service more popular.

Access to the API

The general quota limit is 20 queries per second (QPS) per account.

How it works

Fetch our domain names.
Create a new account by using our domain names.
Sign up only on sites that you have acquired permission to.
The site sends an email message to the address you specify.
A message comes to our SMTP server, processed and added to the database.
You make a request to the API to fetch the message list.
That's it.

API Documentation

Base url: https://22.do/api/v2

OpenApi:

Error handling

Successful

Generally, the request is successful when the response code is 200, 201 or 204 (You could also check if the code is between 200 and 204)

Unsuccessful

Usually, when the request has an error the code is between 400 and 430.

Bad request 400: Something in your payload is missing! Or, the payload isn't there at all.

Unauthorized 401: Your bearer token isn't correct (Or the headers hasn't a token at all!). Remember, every request (Except POST /auth and POST /token) should be authenticated with a Bearer token!

Not found 404: You're trying to access an account that doesn't exist? Or maybe reading a non-existing message? Go check that!

Method not allowed 405: Maybe you're trying to GET a /token or POST a /messages. Check the path you're trying to make a request to and check if the method is the correct one.

Unprocessable entity 422: Some went wrong on your payload. Like, the username of the address while creating the account isn't long enough, or, the account's domain isn't correct. Things like that.

Too many requests 429: You exceeded the limit of 20 requests per second! Try delaying the request by one second!

Authentication

You need to authenticate the request with a bearer token.

How to get it?

You need to make a POST request to the /auth path with mail and password, or use a token make a POST request to the /token obtain bearer token.

Access here to obtain your token.

POST /auth

Body

Name Type Description
address string Your account's mail. Example: [email protected]
password string Your account's password.

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": {
        "Bearer": "xxx.xxx.xxx.xxx",
        "expireTime": 1746168434
    }
}

POST /token

Access here to obtain your token.

Body

Name Type Description
token string Your account's token. Example: 7a3d5e2f8b9c1a6d4f7e0b2c5a8f9d3e

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": {
        "Bearer": "xxx.xxx.xxx.xxx",
        "expireTime": 1746168434
    }
}

Use this Bearer token as

"Authorization":"Bearer $Bearer"

In every request!

Remember! You must use the `Bearer $Bearer` authorization in the headers!

GET /qps/status

Retrieve current QPS rate limit usage, window size, and reset countdown for your account. Calling this endpoint does not consume any QPS quota.

Params

None

Response

{
    "code": 200,
    "status": true,
    "data": {
        "used": 42,
        "limit": 300,
        "window": 15,
        "reset_in": 7,
        "usage_pct": 14.0
    }
}

Domain

GET /domains

Retrieves a list of domains associated with the authenticated user.

Body

None

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": [
        {
            "domain": "example.com",
            "type": "premium"
        },
        {
            "domain": "example1.com",
            "type": "premium"
        },
        {
            "domain": "example2.com",
            "type": "premium"
        },
        {
            "domain": "example3.com",
            "type": "private",
            "mx": true
        },
        {
            "domain": "example4.com",
            "type": "private",
            "mx": true
        }
    ]
}

GET /domains/premium

Retrieves a list of premium domains associated with the authenticated user.

Body

None

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": [
        {
            "domain": "example.com",
            "type": "premium"
        },
        {
            "domain": "example1.com",
            "type": "premium"
        }
    ]
}

GET /domains/private

Retrieves a list of private domains associated with the authenticated user.

Add private domains please access here.

Body

None

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": [
        {
            "domain": "example.com",
            "type": "premium"
        },
        {
            "domain": "example1.com",
            "type": "premium"
        }
    ]
}

Account

POST /account

This API endpoint is used to retrieve a temporary email account. You can obtain details of their temporary email, including email address, account name, domain, and account type (such as premium domains or private domains). Users need to provide a valid authorization token to access this functionality.

Body

None

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": {
        "email": "[email protected]",
        "account": "user",
        "domain": "example.com",
        "type": "premium"
    }
}

GET /account/premium

This API endpoint is used to retrieve a premium temporary email account. Through this interface, users can obtain details of their premium temporary email, including email address, account name, domain, and account type. Users need to provide a valid authorization token to access this functionality.

Body

None

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": {
        "email": "[email protected]",
        "account": "user",
        "domain": "example.com",
        "type": "premium"
    }
}

GET /account/private

This API endpoint is used to retrieve a private temporary email account. Through this interface, users can obtain details of their private temporary email, including email address, account name, domain, and account type. Users need to provide a valid authorization token to access this functionality.

Body

None

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": {
        "email": "[email protected]",
        "account": "user",
        "domain": "example3.com",
        "type": "private"
    }
}

Inbox

POST /inbox

Gets all the Message resources of a given page.When time is empty or not provided, all emails across all time periods will be queried. When time has a value, only emails received after that timestamp will be queried.

Body

Name Type Description
email string (required) Temporary email address. Example: [email protected]
time integer (optional) unix timestamp. Example: 1745411478

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": [
        {
            "time": 1745411165,
            "subject": "subject",
            "from": "noreply ",
            "to": "[email protected]",
            "messageId": "1589e29186e7d311882f8d7b5e07b3d5",
            "expireTime": 1745425565
        }
    ]
}

POST /inbox/message

Retrieves a Message resource with a specific messageId (It has way more information than a message retrieved with POST /inbox )

Body

Name Type Description
messageId string (required) The message you want to get by messageId

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": {
        "time": 1745411165,
        "subject": "subject",
        "body": "body content",
        "html": "html content",
        "from": "noreply ",
        "to": "[email protected]",
        "tos": [
            "[email protected]",
            "[email protected]",
            "[email protected]"
        ],
        "messageId": "1589e29186e7d311882f8d7b5e07b3d5",
        "expireTime": 1745425565
    }
}

DELETE /inbox/message

Retrieves a Message resource with a specific messageId (It has way more information than a message retrieved with POST /inbox )

Body

Name Type Description
messageId string (required) The message you want to delete's messageId

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "Message deleted successfully"
}

Gmail

The Gmail module does not require an premium subscription plan; regular users can use it. After purchasing a gmailId, you can use the API interface to receive emails.

POST /gmail

The response will be paginated, with the number of items per page determined by the limit parameter.
Use the page parameter to navigate through multiple pages of results.
The total count of Gmail IDs will be included in the response, allowing you to determine the total number of pages.
Results are typically ordered by creation date, with the most recently added Gmail IDs appearing first.
This endpoint provides a comprehensive view of all Gmail IDs currently linked to your account.

Body

Name Type Required Description
page integer Optional Specifies the maximum number of Gmail IDs to return per page.
limit integer Required Specifies the page number to retrieve. Pagination starts at page 1.

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": {
        "items": [
            "aa.bb.cc",
            "aa.b.bcc",
            "a.abbcc"
        ],
        "domains": [
            "@gmail.com",
            "@googlemail.com"
        ],
        "count": 3,
        "limit": 20,
        "current": 1
    }
}

POST /gmail/purchase

The cost of purchasing Gmail IDs will be deducted from your account balance.
After successful purchase, the newly acquired Gmail IDs will be immediately available for use.
Each Gmail ID can be used to generate multiple email addresses.
The system will verify that you have sufficient account balance before processing the purchase.
If the purchase is successful, the response will include the details of the newly acquired Gmail IDs.

Body

Name Type Required Description
number integer Required Specifies the number of new Gmail IDs you wish to purchase. This determines how many unique Gmail IDs will be added to your account.

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "Successfully purchased 3 GmailId",
    "data": {
        "items": [
            "aa.bb.cc",
            "aa.b.bcc",
            "a.abbcc"
        ],
        "domains": [
            "@gmail.com",
            "@googlemail.com"
        ]
    }
}

POST /gmail/generate

If gmailId is not specified, the system will randomly select from all Gmail IDs associated with your account.
Setting plus to true generates addresses with the format [email protected], which is useful for email filtering and tracking.
All generated addresses will work with Gmail's systems and will deliver mail to your original Gmail account.
The maximum value for number may be limited based on your account type and permissions.

Body

Name Type Required Description
gmailId string Optional Specifies a particular Gmail ID to use for email generation. If not provided, the system will use all Gmail IDs associated with your account.
number integer Required The number of email addresses to generate. This determines how many unique Gmail addresses will be returned.
plus boolean Required When set to true, generated addresses will include the "+" notation (e.g., [email protected]), which can be used for email filtering. When false or omitted, addresses will use standard Gmail address formats.

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": {
        "items": [
            "aa.bb.cc+2gwhp1f03",
            "aa.bb.cc+oxjhqbrp",
            "aa.bb.cc+hado15fd6",
            "aa.bb.cc+wekzk7",
            "aa.bb.cc+tdic7",
            "aa.bb.cc+9520w",
            "aa.bb.cc+95u7",
            "aa.bb.cc+amk5r4i",
            "aa.bb.cc+qngyem",
            "aa.bb.cc+rhnz"
        ],
        "domains": [
            "@gmail.com",
            "@googlemail.com"
        ]
    }
}

POST /gmail/inbox

Only support Gmail!
Gets all the Message resources of a given page.
When time is empty or not provided, all emails across all time periods will be queried. When time has a value, only emails received after that timestamp will be queried.

Body

Name Type Required Description
email string Required temp gmail address
time integer Optional unix timestamp

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": [
        {
            "time": 1745411165,
            "subject": "subject",
            "from": "noreply ",
            "to": "[email protected]",
            "messageId": "1589e29186e7d311882f8d7b5e07b3d5",
            "expireTime": 1745425565
        }
    ]
}

POST /gmail/message

Retrieves a Message resource with a specific messageId (It has way more information than a message retrieved with POST /gmail/inbox )

Body

Name Type Required Description
messageId string Required The message you want to get by messageId

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": {
        "time": 1745411165,
        "subject": "subject",
        "body": "body content",
        "html": "html content",
        "from": "noreply ",
        "to": "[email protected]",
        "tos": [
            "[email protected]",
            "[email protected]",
            "[email protected]"
        ],
        "messageId": "1589e29186e7d311882f8d7b5e07b3d5",
        "expireTime": 1745425565
    }
}

DELETE /gmail/message

Deletes the Message resource.

Body

Name Type Required Description
messageId string Required The message you want to get by messageId

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "Message deleted successfully"
}

Microsoft

The Microsoft module does not require an premium subscription plan; regular users can use it. After purchasing a microsoft account, you can use the API interface to receive emails.

POST /microsoft

The response will be paginated, with the number of items per page determined by the limit parameter.
Use the page parameter to navigate through multiple pages of results.
The total count of microsoft account will be included in the response, allowing you to determine the total number of pages.
Results are typically ordered by creation date, with the most recently added microsoft account appearing first.
This endpoint provides a comprehensive view of all microsoft account currently linked to your account.

Body

Name Type Required Description
page integer Optional Specifies the maximum number of microsoft account to return per page.
limit integer Required Specifies the page number to retrieve. Pagination starts at page 1.

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": {
        "items": [
            "[email protected]",
            "[email protected]",
            "[email protected]"
        ],
        "count": 3,
        "limit": 20,
        "current": 1
    }
}

POST /microsoft/purchase

The cost of purchasing microsoft account will be deducted from your account balance.
After successful purchase, the newly acquired microsoft account will be immediately available for use.
Each microsoft account can be used to generate multiple email addresses.
The system will verify that you have sufficient account balance before processing the purchase.
If the purchase is successful, the response will include the details of the newly acquired microsoft account.

Body

Name Type Required Description
number integer Required Specifies the number of new microsoft account you wish to purchase. This determines how many unique microsoft account will be added to your account.
outlook boolean Optional When set to true, explicitly selects outlook.com accounts. Can be omitted or set to false.
hotmail boolean Optional When set to true, explicitly selects hotmail.com accounts. Can be omitted or set to false.

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "Successfully purchased 3 microsoft account",
    "data": {
        "items": [
            "[email protected]",
            "[email protected]",
            "[email protected]"
        ]
    }
}

POST /microsoft/generate

If microsoft account is not specified, the system will randomly select from all microsoft account associated with your account.
Setting plus to true generates addresses with the format [email protected], which is useful for email filtering and tracking.
All generated addresses will work with microsoft's systems and will deliver mail to your original microsoft account.
The maximum value for number may be limited based on your account type and permissions.

Body

Name Type Required Description
account string Optional Specifies a particular microsoft account to use for email generation. If not provided, the system will use all microsoft account associated with your account.
number integer Required The number of email addresses to generate. This determines how many unique microsoft account addresses will be returned.
plus boolean Required When set to true, generated addresses will include the "+" notation (e.g., [email protected]), which can be used for email filtering. When false or omitted, addresses will use standard microsoft account address formats.

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": {
        "items": [
            "[email protected]",
            "[email protected]",
            "[email protected]",
            "[email protected]",
            "[email protected]",
            "[email protected]",
            "[email protected]",
            "[email protected]",
            "[email protected]",
            "[email protected]"
        ],
    }
}

POST /microsoft/inbox

Only support microsoft!
Gets all the Message resources of a given page.
When time is empty or not provided, all emails across all time periods will be queried. When time has a value, only emails received after that timestamp will be queried.

Body

Name Type Required Description
email string Required temp microsoft address
time integer Optional unix timestamp

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": [
        {
            "time": 1745411165,
            "subject": "subject",
            "from": "noreply ",
            "to": "[email protected]",
            "messageId": "ms89e29186e7d311882f8d7b5e07b3ms",
            "expireTime": 1745425565
        }
    ]
}

POST /microsoft/message

Retrieves a Message resource with a specific messageId (It has way more information than a message retrieved with POST /microsoft/inbox )

Body

Name Type Required Description
messageId string Required The message you want to get by messageId

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": {
        "time": 1745411165,
        "subject": "subject",
        "body": "body content",
        "html": "html content",
        "from": "noreply ",
        "to": "[email protected]",
        "tos": [
            "[email protected]",
            "[email protected]",
            "[email protected]"
        ],
        "messageId": "1589e29186e7d311882f8d7b5e07b3d5",
        "expireTime": 1745425565
    }
}

DELETE /microsoft/message

Deletes the Message resource.

Body

Name Type Required Description
messageId string Required The message you want to get by messageId

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "Message deleted successfully"
}

Gmail OTP

Buy Gmail addresses for a specific website or app (a "project"), sign up on that website with the address, then fetch the verification code it receives. Each address is a real, standalone Gmail account, not a dot (.) or plus (+) alias like the Gmail module; you get the address and an API link for its codes, not the account password. Regular users can use this module; the price is deducted from your account balance.

  1. Get the project list with POST /project and pick a projectId.
  2. Buy emails with POST /project/purchase. Each email comes with an orderId, a token and an apiLink.
  3. Sign up on the project's website with the email address.
  4. Fetch the code with POST /project/code or the no-login API link. Retry every few seconds while the code has not arrived yet.

Orders do not expire, and you can request the latest code as many times as you need. Every project has an email type (term):

  • long (Long-term): the email keeps receiving codes as long as it stays valid.
  • short (Short-term): use the email soon after purchase; it may stop receiving codes later.

If an order never receives a code, contact support for a refund. Please make a small test purchase before buying in bulk.

POST /project

Lists all projects that are currently available for purchase. price is the price per email in your account currency; term is the email type (long or short, see above).

Body

None (send {})

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": {
        "items": [
            {
                "projectId": "669228c1-c1a0-430b-970c-7040e60dbbde",
                "name": "AWS",
                "price": 0.3,
                "term": "long",
                "intro": "Amazon Web Services",
                "website": "https://aws.amazon.com",
                "googlePlay": "",
                "appStore": ""
            }
        ]
    }
}

POST /project/purchase

Buys emails for a project. The cost is deducted from your account balance, one email at a time; the purchase stops when the balance runs out.
If the upstream rejects an order, that email is refunded immediately and the rest are not purchased.
address may be empty when the email is still being prepared; it will appear in POST /project/orders shortly, and POST /project/code works either way.

Body

Name Type Required Description
projectId string Required The project to buy, from POST /project.
quantity integer Required Number of emails to buy, 1 to 10.

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "Successfully purchased 2 email(s).",
    "data": {
        "items": [
            {
                "orderId": "ebc9f555-0195-4f35-b28b-9f6b1bb99f94",
                "address": "[email protected]",
                "token": "f6f92d918ecae0e1a983c1d2e4b5a6c7",
                "apiLink": "https://22.do/mail/code/f6f92d918ecae0e1a983c1d2e4b5a6c7"
            },
            {
                "orderId": "3ab796ee-0647-4056-87bb-a80fbf474c2c",
                "address": "",
                "token": "0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a",
                "apiLink": "https://22.do/mail/code/0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a"
            }
        ],
        "success": 2,
        "failed": 0,
        "insufficient": false,
        "price": 0.3
    }
}

When nothing could be purchased, status is false and msg explains why, e.g. Insufficient balance, please recharge!

POST /project/orders

Lists your orders, newest first. Use it to pick up addresses that were still being prepared at purchase time. term is the email type at the time of purchase.

Body

Name Type Required Description
page integer Optional Page number, starting at 1.
limit integer Optional Items per page: 10, 50, 100, 200 or 500. Default 10.
projectName string Optional Only orders of this project.
email string Optional Search by email address (partial match).
status string Optional waiting: no code received yet; active: a code has been received; failed; refunded. Omit for all orders.

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": {
        "items": [
            {
                "orderId": "ebc9f555-0195-4f35-b28b-9f6b1bb99f94",
                "projectId": "669228c1-c1a0-430b-970c-7040e60dbbde",
                "projectName": "AWS",
                "term": "long",
                "address": "[email protected]",
                "token": "f6f92d918ecae0e1a983c1d2e4b5a6c7",
                "apiLink": "https://22.do/mail/code/f6f92d918ecae0e1a983c1d2e4b5a6c7",
                "status": "success",
                "failReason": "",
                "price": 0.3,
                "createTime": 1790824982
            }
        ],
        "count": 1,
        "limit": 10,
        "current": 1
    }
}

Order status

Status Description
pending Waiting for the verification code. Orders do not time out; contact support if no code ever arrives.
success A code has been received. You can keep fetching the latest code while the email stays valid.
failed The email became invalid or could not be delivered (see failReason). Contact support for a refund.
refunded The fee has been returned to your balance.

POST /project/code

Gets the verification code of one of your orders. The result is the same as the API link.

Body

Name Type Required Description
orderId string Required The order, from POST /project/purchase or POST /project/orders.

Params

None

Response

{
    "code": 200,
    "status": true,
    "msg": "success",
    "data": {
        "code": "853106"
    }
}

Until a code is available, status is false, data is null and msg tells you what to do:

msg What to do
Waiting for verification code The code has not arrived yet. Retry in a few seconds.
The email is being prepared, please try again later The email address is still being assigned. Retry in a few seconds.
The email account is invalid, please contact support for a refund The email can no longer receive codes. Contact support for a refund.
The email could not be delivered, please contact support for a refund The email was never delivered. Contact support for a refund.
This order has been refunded The fee has been returned to your balance; the order can no longer be used.
Order not found The orderId does not exist or does not belong to your account.

GET https://22.do/mail/code/{token}

A public link for fetching the code without a Bearer token, handy for other programs and tools. Every order has its own link (apiLink). Anyone who has the link can read the code, so keep it private; resetting the token on the Orders page disables the old link immediately.

Response

Same as POST /project/code (without the code: 200 field). An unknown token returns {"status": false, "msg": "Invalid token", "data": null}.

Questions and suggestions

If you have any questions or suggestions, please contact us via email [email protected].

Tech stack

Our stack includes API-Platform, Mercure, Nuxt.js, Haraka, Caddy, MongoDB, Node.js, CentOS

Updated on Tuesday, April 26, 2025