-
Notifications
You must be signed in to change notification settings - Fork 0
v2 API Endpoints
The TempMail v2 API is different from v1, so please read carefully before upgrading.
NEW CUSTOM DOMAINS: Please use the new custom domain method
Base URL: https://api.tempmail.lol/v2
Feel free to join the Discord Server if you need help with anything API related. Email us if you need assistance with billing, subscriptions, or anything else: contact@bananacrumbs.us.
Inboxes expire after a certain amount of time:
| Subscription | Inbox Lifespan |
|---|---|
| free | One Hour |
| TempMail Plus | Ten Hours |
| TempMail Ultra | Thirty Hours |
Inboxes no longer expire after 10 minutes since last check.
These expiration dates do not apply to custom domain inboxes.
Custom Domains have an inbox size of 500 emails.
Custom Domain Inboxes may be erased after one month of last check to protect user's privacy (and to free up storage).
First, you do not need an API key to use the free tier; however, you will need either an API Key (or a legacy ID/Token) to use TempMail Plus or Ultra.
Authorization: Bearer tm.1234567890.abcdefghijklmnopqrstuvwxyzanditkeepsgoingon
Make sure to copy the FULL API Key from your dashboard. If you lose it, you will need to make a new one.
This authorization uses the form id,token, such as:
Authorization: 123456781234567812345678,ABCDEFGHIJKLMNOPQRSTUVWXYZ
Replace with your own BananaCrumbs ID and token.
No new time can be added to legacy accounts; however, you can merge legacy accounts here after creating a new TempMail Account.
API Types haven't changed since v1.
| Field | Type | Description |
|---|---|---|
| from | string | Email address of the sender |
| to | string | The address the email was sent to |
| subject | string | The email subject |
| body | string | The text body of the email |
| date | number | Unix timestamp (millis) the email was received |
| ip | string | The IP address of the sender (not always accurate) |
| html | ?string | The HTML of the email (possibly undefined) |
| Field | Type | Description |
|---|---|---|
| address | string | The email address of this inbox |
| token | string | The token used to access this inbox |
Create an inbox with optional POST parameters as JSON data.
| JSON field | Type | Description |
|---|---|---|
| domain | ?string | Specific domain to use (do not use this for custom domains!) |
| community | ?boolean |
true to use community, false otherwise (default false) |
| prefix | ?string | Prefix of the email address to make |
You may also use a custom domain in this field if you have configured it for v2 custom domains.
| JSON field | Type | Description |
|---|---|---|
| address | string | The email address you have created |
| token | string | The token used to access the inbox |
| JSON field | Type | Description |
|---|---|---|
| error | string | An error explaining why an email could not be created |
There may be non-JSON formatted errors on this endpoint (in the event the service is offline).
Get an inbox's emails from a token.
| Query Parameter | Type | Description |
|---|---|---|
| token | string | The token given when you created your email address. |
| JSON field | Type | Description |
|---|---|---|
| emails | Email[] | Array of Email objects |
| expired | boolean |
true if the inbox has expired, false otherwise |
Custom domains can get complicated, so I'm giving them their own section. Also, you need TempMail Plus or Ultra to use custom domains.
First, create the UUID for your inbox on https://accounts.tempmail.lol after creating your account.
Behind the scenes, that accounts page calls the following:
with the following POST data:
| JSON field | Type | Description |
|---|---|---|
| domain | string | Domain to get the UUID for |
| JSON field | Type | Description |
|---|---|---|
| uuid | string | The UUID to use for your domain |
You will add this to a TXT record named [UUID].yourdomain.com with the value of tm-custom-domain-verification.
If you are using a subdomain, add it to [UUID].subdomain.yourdomain.com instead.
| JSON field | Type | Description |
|---|---|---|
| error | string | An error explaining why an email could not be created |
| Query Parameter | Type | Description |
|---|---|---|
| domain | string | The domain to check |
| to | ?string | address to use to filter emails* |
* this will only clear inboxes which are to this address, and will not clear the rest of the inbox. Your inbox may still fill up to the 500 email limit.
You can also get this value on https://accounts.tempmail.lol. Behind the scenes, this is what it calls.
Requires authorization. No parameters or data for this method.
| JSON field | Type | Description |
|---|---|---|
| status | string | Always default to "OK" on success. |
| record_value | string | A string starting with "tempmail-wc-" that will be the value of the txt record to add. |
See the wildcard setup on the right for more information.
You need TempMail Ultra to use Private Webhooks.
Get the UUID for your webhook (this will be the same UUID as custom domains).
| Query Parameter | Type | Description |
|---|---|---|
| domain | string | The domain to get the UUID for |
| JSON field | Type | Description |
|---|---|---|
| txt_name | string | Name to use for the TXT record |
| txt_value | string | Value tm-custom-domain-verification
|
| JSON field | Type | Description |
|---|---|---|
| domain | string | Domain to set the webhook for |
| url | string | URL to forward emails to |
Sets the webhook for this domain. All emails received on the domain with the webhook will be forwarded.
| JSON field | Type | Description |
|---|---|---|
| success | true | Always true
|
| message | string | Success info message |
| JSON field | Type | Description |
|---|---|---|
| error | string | Error message |
| Query Parameter | Type | Description |
|---|---|---|
| domain | string | The domain to delete the webhook from |
You need TempMail Ultra to use Webhooks.
You can have all inboxes you create with your account automatically forward their emails to a webhook you provide.
Webhooks will send an Email object as JSON POST data.
With the following POST data:
| JSON field | Type | Description |
|---|---|---|
| url | string | URL to forward emails to |
| JSON field | Type | Description |
|---|---|---|
| status | string | Success message, either if the webhook did not exist or if it was successfully deleted. |
Get statistics for the server. This is what is displayed on the homepage of the website.
| JSON field | Type | Description |
|---|---|---|
| emails_received | number | Amount of emails received |
| total_inboxes | number | Total amount of inboxes created (since Feb 17 2024) |
| clients_connected | number | Total amount of active inboxes |
This updates once every 10-15 seconds.
POST data:
| JSON field | Type | Description |
|---|---|---|
| domain | string | The domain to add, setup on the TempMail website |