Temp Mail API Getting Started: Free Receive Email API Guide

The temp mail API lets you programmatically create disposable inboxes, receive emails, and configure webhook notifications. This guide shows you how to integrate YYDS Mail API into your application.

API Overview

YYDS Mail provides a complete RESTful API covering the full temp mail lifecycle:

| Feature | Endpoint | Method | |---------|----------|--------| | Create inbox | /v1/accounts | POST | | List inboxes | /v1/accounts | GET | | Get messages | /v1/accounts/{id}/messages | GET | | Message detail | /v1/messages/{id} | GET | | Configure webhook | /v1/webhooks | POST |

Full endpoint list in API docs. All responses are JSON with { success, data, error } structure.

Authentication: Get an API Key

1. Register and log in to YYDS Mail
2. Go to Console → API Keys
3. Create a new key with permissions
4. Copy the key (format: AC-xxxxxxxxxxxx)

Pass the key via X-API-Key header:

curl https://maliapi.215.im/v1/accounts \
  -H "X-API-Key: AC-your-key-here"

Security: never commit API keys to git. Use environment variables in production.

Create a Temp Mail Inbox

curl https://maliapi.215.im/v1/accounts \
  -X POST \
  -H "X-API-Key: AC-your-key-here" \
  -H "Content-Type: application/json"

JavaScript example:

const res = await fetch("https://maliapi.215.im/v1/accounts", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.YYDS_API_KEY,
    "Content-Type": "application/json",
  },
});
const { data } = await res.json();
console.log("Temp mail address:", data.address);

Receive Emails

Query the inbox with GET /v1/accounts/{id}/messages. For real-time scenarios, use Webhook instead of polling.

Webhook for Real-Time Notifications

When a new email arrives, YYDS Mail POSTs to your URL:

app.post("/webhooks/mail", (req, res) => {
  const { message } = req.body;
  console.log("Received:", message.subject);
  // Extract verification code, trigger workflow...
  res.json({ ok: true });
});

Webhook setup details in the Webhook guide.

Rate Limits and Quota

The free tier has daily API call limits. Exceed requires waiting for reset or upgrading. Best practices:

• Use Webhook instead of polling to save quota
• Cache results to avoid repeated requests
• Implement exponential backoff for 429 errors

FAQ

Is there a call limit? Yes. Free tier has daily quota, paid tiers have more. See pricing.

What languages are supported? Any language that can make HTTP requests: Python, JavaScript, Go, PHP, Java, curl. See full docs.

Can the API send emails? No. YYDS Mail is receive-only. The API only supports receiving and managing emails.

Want to integrate temp mail with code? See full API docs, or register to get an API key. Read what is temp mail for basics.