Reference

API Documentation

Public gateway endpoints for mailbox generation, polling, cleanup, and stats.

Use the API to generate temporary inboxes, poll messages, read a specific mail, and clean up after verification flows.

Use cases and basics

Base URL	`http://tz.beiyuka.com`
Auth	All endpoints use Authorization: Bearer <api-key>.
Provider	Pass provider when you need deterministic routing across multiple upstream providers.

GET /api/generate-email

Generate mailbox

curl http://tz.beiyuka.com/api/generate-email \
  -H 'Authorization: Bearer <api-key>'

Response example

{
  "success": true,
  "data": {
    "email": "demo123@mailto.plus"
  },
  "error": ""
}

POST /api/generate-email

Field	Type	Required	Description
`prefix`	string	No	Mailbox prefix.
`domain`	string	No	Requested domain.
`provider`	string	No	Explicit provider name.

Generate mailbox with payload

curl -X POST http://tz.beiyuka.com/api/generate-email \
  -H 'Authorization: Bearer <api-key>' \
  -H 'Content-Type: application/json' \
  -d '{"provider":"legacy"}'

Response example

{
  "success": true,
  "data": {
    "email": "otp-bot@mailto.plus"
  },
  "error": ""
}

GET /api/emails

List mailbox

curl 'http://tz.beiyuka.com/api/emails?email=user@example.com' \
  -H 'Authorization: Bearer <api-key>'

Response example

{
  "success": true,
  "data": {
    "emails": [
      {
        "id": "MAIL_ID",
        "email_address": "user@example.com",
        "from_address": "no-reply@example.com",
        "subject": "Your code",
        "content": "Code: 123456",
        "html_content": "<p>Code: <strong>123456</strong></p>"
      }
    ],
    "count": 1
  },
  "error": ""
}

Fields

Field	Type	Description
`id`	string	Mail identifier.
`email_address`	string	Mailbox address.
`from_address`	string	Sender address.
`subject`	string	Subject line.
`content`	string	Plain-text body.
`html_content`	string	Rendered HTML body.

GET /api/email/:id

Providing email improves lookup reliability.

Get one mail

curl 'http://tz.beiyuka.com/api/email/MAIL_ID?email=user@example.com' \
  -H 'Authorization: Bearer <api-key>'

Response example

{
  "success": true,
  "data": {
    "id": "MAIL_ID",
    "email_address": "user@example.com",
    "from_address": "no-reply@example.com",
    "subject": "Your code",
    "content": "Code: 123456",
    "html_content": "<p>Code: <strong>123456</strong></p>"
  },
  "error": ""
}

DELETE /api/email/:id

Delete one mail

curl -X DELETE 'http://tz.beiyuka.com/api/email/MAIL_ID?email=user@example.com' \
  -H 'Authorization: Bearer <api-key>'

Response example

{
  "success": true,
  "data": {
    "message": "Deleted email."
  },
  "error": ""
}

DELETE /api/emails/clear

Clear mailbox

curl -X DELETE 'http://tz.beiyuka.com/api/emails/clear?email=user@example.com' \
  -H 'Authorization: Bearer <api-key>'

Response example

{
  "success": true,
  "data": {
    "message": "Cleared emails.",
    "count": 1
  },
  "error": ""
}

GET /api/stats

Read stats

curl http://tz.beiyuka.com/api/stats \
  -H 'Authorization: Bearer <api-key>'

Stats envelope

{
  "success": true,
  "data": {
    "proxy": {
      "totalUpstreamCalls": 1234,
      "todayUpstreamCalls": 56,
      "activeApiKeys": 3
    },
    "providers": [
  {
    "name": "linshiyouxiang",
    "isDefault": false
  },
  {
    "name": "mailgw",
    "isDefault": false
  },
  {
    "name": "mailtm",
    "isDefault": true
  }
]
  },
  "error": ""
}

Stats Fields

Field	Type	Description
`proxy.totalUpstreamCalls`	number	Total upstream calls recorded by the gateway.
`proxy.todayUpstreamCalls`	number	Today's upstream calls in UTC.
`proxy.activeApiKeys`	number	Currently active API key count.
`providers`	array	List of configured and enabled providers.

Examples

JavaScript

fetch("http://tz.beiyuka.com/api/generate-email", {
  headers: { Authorization: "Bearer <api-key>" }
}).then((response) => response.json())

Python

import requests

resp = requests.get(
    "http://tz.beiyuka.com/api/emails",
    params={"email": "user@example.com"},
    headers={"Authorization": "Bearer <api-key>"},
    timeout=30,
)
print(resp.json())

Practical Tips

Poll every 2-5 seconds for OTP workflows.
List the mailbox first to build the mail-id mapping.
Prefer html_content when rendered email fidelity matters.
Pass email explicitly for detail and delete operations.