Mailjs

A JavaScript wrapper around the mail.tm api.

Probably one of the best API for creating temporary email accounts.

• Usage of our API for illegal activity is strictly prohibited.
• It is forbidden to sell programs or earn from it that exclusively uses our API (for example, creating a competing temp mail client and charging for it's usage).
• The general quota limit is 8 queries per second (QPS) per IP address.

Installation

npm

npm install @bloodgang/mailjs

yarn

yarn add @bloodgang/mailjs

CDN

<!-- It is only needed to listen to new messages. -->
<script src="https://cdn.jsdelivr.net/gh/bloodgang/[email protected]/eventsource.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@bloodgang/[email protected]/dist/mailjs.min.js"></script>

Quickstart

• Nodejs (CommonJS)

const Mailjs = require("@bloodgang/mailjs");

• Nodejs (ESM)

import Mailjs from "@bloodgang/mailjs";

• Browser

<!-- You can exlude this if not listening to events. -->
<script src="https://cdn.jsdelivr.net/gh/bloodgang/[email protected]/eventsource.min.js"></script>
<!-- Mailjs library -->
<script src="https://cdn.jsdelivr.net/npm/@bloodgang/[email protected]/dist/mailjs.min.js"></script>

EventSourcePolyfill is only for listening to new incoming messages, see Events title for more information. Add EventSourcePolyfill before Mailjs.

const mailjs = new Mailjs();

mailjs.createOneAccount().then((account) => console.log(account.data));

For more reference visit /examples directory.

Documentation

Default domain domain mai.gw You can override it

const mailjs = new Mailjs();
mailjs.useDomain("mail.tm");

Returns a Promise object after the function is called. If the request is sent correctly, status returns true. If it returns incorrect, the status will be false and the message in the data is also added. If there is no error, status always returns true.

A successfull response example:

{
  "status": true,
  "message": "ok",
  "data": {}
}

A failed response example:

{
  "status": false,
  "message": "Invalid credentials.",
  "data": {}
}

Example use:

const acc = await mailjs.createOneAccount();

// If there is a error.
if (!acc.status) {
  // Show the cause of the error.
  console.error(acc.message);

  return;
}

// If successful, access the data.
console.log(acc.data);

To see all results, check out the API page: https://api.mail.tm/.

User needs to login to access JWT token. Registration does not return this information, log in after registration.

After the login process, the user's JWT token and ID are assigned to mailjs.token and mailjs.id

Domain

List Domains

mailjs.getDomains().then(console.log);

Get Domain

mailjs.getDomain("[domain id]").then(console.log);

Account

Create Account

mailjs.register("[email protected]", "password").then(console.log);

Login

mailjs.token and mailjs.id can be used to access the user token and id later.

mailjs.login("[email protected]", "password").then(console.log);

Login With Token

If you use the JWT token stored in mailjs.token after login, it will allow you to login without username and password.

mailjs.loginWithToken("eyJ0eXAiO...").then(console.log);

Get Account Data

mailjs.me().then(console.log);

Delete Account

mailjs.deleteMe().then(console.log);

You can also use the id to access the user's information and delete their account.

mailjs.deleteAccount("[account id]").then(console.log);

mailjs.getAccount("[account id]").then(console.log);

Message

List messages

Gets all the Message resources of a given page.

mailjs.getMessages().then(console.log);

Read a message

Retrieves a Message resource with a specific id (It has way more information than a message retrieved with GET /messages but it hasn't the "intro" member)

mailjs.getMessage("[message id]").then(console.log);

Delete a message

mailjs.deleteMessage("[message id]").then(console.log);

Make a message readed or unreaded.

true for make readed. false for make unreaded.

mailjs.setMessageSeen("[message id]", true).then(console.log);

Events

Events are the Server Sent Events which are fired when message arrive, seen or delete. It also fires the error, open state.

on

Open an event listener to messages and error.

// Add it before other activities if you need it.
mailjs.on("open", (msg) => console.log("Event listening has begun."));

// When a new message arrives.
mailjs.on("arrive", (msg) =>
  console.log(`Message id: ${msg.id} has arrived (${msg.intro}).`)
);

// When a message is marked as read.
mailjs.on("seen", (msg) =>
  console.log(`Message id: ${msg.id} marked as seen.`)
);

// When a message is deleted.
mailjs.on("delete", (msg) =>
  console.log(`Message id: ${msg.id} has been deleted.`)
);

// If an error occurs during listening.
mailjs.on("error", (err) => console.error("Something went wrong:", err));

off

Clears the events and safely closes event listener.

mailjs.off();

Source

Get source

Gets a Message's Source resource (If you don't know what this is, you either don't really want to use it or you should read this!)

mailjs.getSource("[message id]").then(console.log);

Helper Methods

Create random account.

Creates and logs in an account with a random username and password.

mailjs.createOneAccount().then(console.log);

Response

{
  "status": true,
  "message": "ok",
  "data": {
    "username": "[email protected]",
    "password": "my-password"
  }
}

Questions And Suggestions

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