Email Service

Mail sending plus virtual mailbox send/receive. 3 channels are currently available, with more platforms/channels to come.

/api/email/

Service Description

The email service splits sending and receiving into three channels: Email v1 sends transactional mail with the platform mailbox, suited to verification codes, notifications and alerts; VMEmail and VMEmail(mail.cx) provide temporary (disposable) mailboxes that generate a random address and receive incoming mail, which is handy for registration checks, API integration and automated tests that need a one-off address.

The three channels differ in authentication: the VMEmail channel is open and can be debugged without signing, while Email v1 and the mail.cx channel require project signature authentication.

Temporary mailbox polling is long-polling: when there is no new mail the request hangs for about 25 seconds before returning an empty list. This is expected, so do not treat it as a failure based on a short timeout. Mail is retained for a limited time, so retrieve anything important promptly.

Email v1

Send Email (default channel) Signature Required

Send text/HTML emails to multiple recipients. Signature Required.

POST /api/email/v1/send Total calls: 2

Send Email

Send an email to one or more recipients.

Email subject *

Email subject (Required)

Email body *

Email body content (Required)

Recipient Email *

Recipient email (Required, multiple values supported)

Multiple values: Separate multiple email addresses with commas or line breaks, or pass the same field multiple times

Recipients can be supplied in two ways: repeat the same field multiple times, or separate them with commas within a single field.
On success, data contains subject / recipients / count; a failed send is reported as an external service error.

VMEmail

VMEmail (minmail.app) Temporary Mailbox Available · No Signature

Generate/reuse a temporary mailbox and receive emails; Open (No signature required).

POST /api/email/VMEmail/minmail/generate Total calls: 2

Generate/Get Temporary Mailbox

Generate a brand-new temporary mailbox, or reuse an existing one with visitor_id.

Visitor ID

Optional: if omitted, a random value is generated; pass an existing value to reuse a mailbox within its validity period

Expiry Time (minutes)

Optional: mailbox validity in minutes, a positive integer, Default 1440 (24 hours)

Force New

Optional: when true, force a new mailbox to be generated, discarding the original mailbox and its emails

Keep the visitor_id returned by generate safe; it must be reused when querying emails.

GET /api/email/VMEmail/minmail/emails Total calls: 0

Get Email List

Get the list of emails received by the current temporary mailbox.

Visitor ID *

Required: the visitor_id returned by the generate API

VMEmail(mail.cx)

VMEmail (mail.cx) temporary mailbox (receive only) Signature Required

mail.cx temporary mailbox: the address is generated locally at random with no registration, and the address itself is the unique identifier (mail is kept for about 1 hour); the server keeps no session, so queries must send the address back. Requires a project signature.

GET /api/VMEmail_mailcx/domains Total calls: 14

Get Available Domains

Get all currently available suffix domains, used to specify domain when generating a mailbox.

data is an array of domain strings such as ddker.com, 9k3r.com and uqu.me; on upstream failure the built-in default domains are returned so the service stays usable.

POST /api/VMEmail_mailcx/generate Total calls: 21

Generate Temporary Mailbox

Generate a temporary mailbox address (receive only) and return the address and the client ID.

Suffix Domain

Optional: specify the suffix domain; defaults to uqu.me

Client ID

Optional: client identifier (X-Client-ID); if omitted the server generates one at random, and reusing an existing value reuses the same identity

The request body is an application/x-www-form-urlencoded form.
data: {address, domain, client_id}; address is the mailbox address, and client_id should be saved and sent back when querying mail later.

GET /api/VMEmail_mailcx/emails Total calls: 609

Get Email List

Fetch the mail summary list of a mailbox (long polling; hangs for about 25 seconds and returns an empty list when there is no new mail).

Mailbox Address *

Required: mailbox address, from the response of Generate Temporary Mailbox

Incremental Timestamp (seconds)

Optional: non-negative integer timestamp (seconds); if omitted all current mail is returned, otherwise only mail newer than that time

Client ID

Optional: keep it the same as the client_id used when generating the mailbox

The upstream uses long polling: with no new mail it hangs for about 25 seconds before returning an empty list, so the client HTTP timeout should exceed 35 seconds.
data is an array of mail summaries (id / from_name / from_email / subject / preview_text / preview_status / size / created_at); use the id with Get Mail Detail for the full body.

GET /api/VMEmail_mailcx/email_detail Total calls: 17

Get Mail Detail

Get the full detail by mail id (including the complete body and attachments).

Mail ID *

Required: unique mail identifier (max length 128)

Client ID

Optional: keep it the same as the client_id used when generating the mailbox

data contains id / from / from_email / from_name / to / subject / text_body / html_body / attachments / date / created_at; the actual response prevails.
Returns 20030 when the mail does not exist (or has expired, since mail is kept for about 1 hour).