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!

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.

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"
}

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