TempMail Custom Domain Guide

This is a guide on how to use Custom Domains for TempMail

You are highly recommended to use Custom Domains on API v2.

Custom domains v2 work differently than v1. This guide will ONLY cover v2. v1 is an old system and is not nearly as secure, so please do not use it anymore.

Step zero (optional, for legacy account owners)

If you are a legacy BananaCrumbs ID owner, migrate your BananaCrumbs ID in the accounts page at https://accounts.tempmail.lol/ (this is not required; however, this guide will assume you have a new account).

Otherwise, if you already have an account with your email, you are ready to proceed.

Step one: Get your records

First, you will need to set your domain records. Invalid records could lead to the inability to access your domain over our API, email delivery failure, or both.

To do this, you will need to find the records for setting up your Custom Domain on https://accounts.tempmail.lol/

Single Domain or Sub-Domain

1. Login to https://accounts.tempmail.lol/ with your email and password (you cannot do this with a legacy account)
2. Click on "View Custom Domain Emails"
3. Click on "Setup Custom Domain"
4. Enter your domain and click Submit. It may take several seconds.

Wildcard Subdomain

1. Login to https://accounts.tempmail.lol/ with your email and password (you cannot do this with a legacy account)
2. Click on "Get Wildcard Value"
3. Follow https://github.com/tempmail-lol/server/wiki/Wildcard-Custom-Domains to setup the wildcard.

Step two: create inboxes

As of April 5th 2024, TempMail offers two different ways of accessing your Custom Domain emails, one creates a single inbox for your domain, the other returns EVERY email on your custom domain.

Make sure you are authorized for each request with your API key on the dashboard:

Authorization: Bearer tm.123456789.examplekey

(the actual API key will be much longer).

To create an inbox with your domain, you can use the existing POST /v2/inbox/create endpoint.

Here's an example:
POST https://api.tempmail.lol/v2/inbox/create With data:

{
  "domain": "yourdomain.com",
  "prefix": "optional-prefix"
}

Will return:

{
  "address": "[email protected]",
  "token": "<random token used to access>"
}

Only your account can access your domain, verified using the TXT records.

Note that there is no random suffix. You can create any address you want on your own custom domain. If it expires, you will no longer receive emails; however, you can re-create it as long as you own the domain and have an active subscription.

If you create an address which already exists, the existing address will be returned with the same token, and the expiration time will be updated according to your subscription.

Afterwards, you can simply use the inbox endpoint to get the emails:
GET https://api.tempmail.lol/v2/inbox?token=yourtokenhere

Where yourtokenhere is the token received from the create inbox endpoint.

Step three

There is no step three! If you need help, join our Discord Server or contact us via email.