DuckMail Documentation

DuckMail supports optional API Key configuration to unlock additional features.

Benefits of using an API Key

• Without API Key: Uses public domains; all basic functions are available.
• With API Key: Grants access to more domain selections and the ability to create accounts using private domains.

How to configure an API Key in the UI

1. Click the Settings button in the top right corner of the application.
2. Locate the "API Key Settings" area.
3. Enter your API Key.
4. Click Save to apply the changes.

How to obtain an API Key

1. Visit https://domain.duckmail.sbs.
2. Authenticate via LinuxDo.
3. Select the API Key option in the left sidebar to create a new key.

Using an API Key allows you to access more domain choices and create email accounts using private domains.

How to use an API Key in the Web UI

1. Click the settings button in the top right corner.
2. Enter your API Key in the "API Key Settings" area.
3. Click save to apply.

How to obtain an API Key

1. Visit https://domain.duckmail.sbs.
2. Log in via LinuxDo authentication.
3. Click the API Key option in the sidebar to create a new key.

Authentication Behavior

• Without API Key: All endpoints are accessible. When creating an account, you receive a token for subsequent email operations. You are limited to public domains.
• With API Key: The Domains and Accounts endpoints support an additional API Key Header. This grants access to private domains associated with that key.

DuckMail provides a self-hosted email backend supporting the following core operations:

• Account Management: Create and login to temporary email accounts.
• Email Reception: Real-time email receiving and viewing (supports Mercure SSE for notifications).
• Domain Retrieval: Get available email domains.
• Real-time Notifications: Real-time message push via Mercure Hub.

Detailed API documentation and a debugging interface can be found at: https://www.duckmail.sbs/en/api-docs.

When using the DuckMail API, be aware of the following constraints:

• Rate Limit: 12 QPS (Queries Per Second).
• Email Retention: Emails are kept for three days, after which they are automatically deleted.
• Account Expiration:
  • When creating accounts via API, use the expiresIn parameter (in seconds).
  • 0 or -1 means the account never expires.
  • If omitted, the default is 24 hours auto-cleanup.
  • Accounts created via the Web UI default to never expire.
• Authentication: There is no password recovery functionality.

When using the DuckMail API, be aware of the following constraints:

• Rate Limiting: The request frequency is limited to 12 QPS (Queries Per Second). For special use cases (e.g., public interest projects), you may request a quota increase via email.
• Email Retention: Emails are stored for three days, after which they are automatically deleted.
• Account Expiration:
  • When creating an account via the API, you can set the expiresIn parameter (in seconds).
  • 0 or -1 = The account will never expire.
  • If not provided = The account is automatically cleaned up after 24 hours.
  • Note: Accounts created manually via the web interface do not expire by default.
• Password Recovery: There is no password recovery functionality.

The MessageDetail interface extends Message to provide the full content of an email, including cc, bcc, plain text, html arrays, and a list of attachments with their respective metadata.

export interface MessageDetail extends Message {
  cc?: string[]
  bcc?: string[]
  text: string
  html: string[]
  attachments?: {
    id: string
    filename: string
    contentType: string
    disposition: string
    transferEncoding: string
    related: boolean
    size: number
    downloadUrl: string
  }[]
}

The Account interface represents a user account or an API credential. It tracks usage via quota and used fields. It also supports local storage of authentication credentials like password and token, and can be associated with a specific providerId (defaulting to 'duckmail').

export interface Account {
  id: string
  address: string
  quota: number
  used: number
  isDisabled: boolean
  isDeleted: boolean
  createdAt: string
  updatedAt: string
  password?: string // 存储密码用于重新获取token
  token?: string // 存储该账户的token
  providerId?: string // 账户所属的API提供商ID，用于向后兼容，默认为'duckmail'
}

The Message interface represents a summary of an email. It includes sender (from) and recipient (to) information, subject, an introductory snippet (intro), and metadata like size and downloadUrl.

export interface Message {
  id: string
  accountId: string
  msgid: string
  from: {
    name: string
    address: string
  }
  to: {
    name: string
    address: string
  }[]
  subject: string
  intro: string
  seen: boolean
  isDeleted: boolean
  hasAttachments: boolean
  size: number
  downloadUrl: string
  createdAt: string
  updatedAt: string
}

The ApiProvider interface defines the configuration for an email API service, including its baseUrl and mercureUrl (for real-time updates). CustomApiProvider is a specialized version where isCustom is explicitly set to true.

export interface ApiProvider {
  id: string
  name: string
  baseUrl: string
  mercureUrl: string
  isCustom?: boolean
}

export interface CustomApiProvider extends ApiProvider {
  isCustom: true
}

The Domain interface represents an email domain available in the system. A domain is considered usable only if isVerified is true. If ownerId is null, the domain is a system-wide public domain.

export interface Domain {
  id: string
  domain: string
  isVerified?: boolean // 是否已验证（已验证才可用）
  ownerId?: string // 域名所有者ID，null 表示系统公共域名
  providerId?: string // 域名所属的API提供商ID
  providerName?: string // 提供商名称，用于显示
  createdAt?: string
  updatedAt?: string
}