API Docs
Wild Duck Mail Server is a scalable IMAP / POP3 server that natively exposes internal data through an HTTP API.
- API Usage Info
- Users
- Authentication
- 2FA
- Application Specific Passwords
- Addresses
- Mailboxes
- Messages
- Quota
- Updates
Table of contents generated with markdown-toc
All successful responses look like the following:
{
"success": true,
other response specific fields
}
All failed responses look like the following:
{
"error": "Some error message"
}For paging lists longer than allowed limit, Wild Duck API returns URLs for next and previous pages. When paging do not change these URLs yourself. If query arguments are changed then the results might be unreliable.
{
"success": true,
"total": 200,
"page": 2,
"results": ["a list of results"],
"prev": "/an/url/to/previous/page?arg1=123&arg2=345",
"next": "/an/url/to/next/page?arg1=123&arg2=345"
}User accounts
Returns data about existing users
Parameters
- query is an optional string to filter username (partial match), by default all users are listed
- limit is an optional number to limit listing length, defaults to 20
Example
curl "http://localhost:8080/users?query=testuser01"
Response for a successful operation:
{
"success": true,
"query": "testuser01",
"total": 1,
"page": 1,
"prev": false,
"next": false,
"results": [
{
"id": "5970860fcdb513ce633407a1",
"username": "testuser01",
"address": "[email protected]",
"quota": {
"allowed": 1073741824,
"used": 0
},
"disabled": false
}
]
}Returns data about a specific user
Parameters
- user is the ID of the user
Example
curl "http://localhost:8080/users/5970860fcdb513ce633407a1"
Response for a successful operation:
{
"success": true,
"id": "5970860fcdb513ce633407a1",
"username": "testuser01",
"address": "[email protected]",
"retention": false,
"limits": {
"quota": {
"allowed": 1073741824,
"used": 0
},
"recipients": {
"allowed": 2000,
"used": 0,
"ttl": false
},
"forwards": {
"allowed": 2000,
"used": 0,
"ttl": false
}
},
"activated": true,
"disabled": false
}Recipient/forward limits assume that messages are sent using ZoneMTA with zonemta-wildduck plugin, otherwise the counters are not updated.
Creates a new user, returns the ID upon success.
Parameters
- username (required) is the username of the user. This is not an email address but authentication username, use only letters and numbers
- password (required) is the password for the user
- address is the main email address for the user. If address is not set then a new one is generated based on the username and current domain name
- name is the name for the user
- forward is an email address to where all messages are forwarded to
- targetUrl is an URL to where all messages are uploaded to
- quota is the maximum storage in bytes allowed for this user. If not set then the default value is used
- retention is the default retention time in ms for mailboxes. Messages in Trash and Junk folders have a capped retention time of 30 days.
- language is the language code for the user, eg. "en" or "et". Mailbox names for the default mailboxes (eg. "Trash") depend on the language
- recipients is the maximum number of recipients allowed to send mail to in a 24h window. Requires ZoneMTA with the Wild Duck plugin
- forwards is the maximum number of forwarded emails in a 24h window. Requires ZoneMTA with the Wild Duck plugin
- ip is the IP address the request was made from
Example
curl -XPOST "http://localhost:8080/users" -H 'content-type: application/json' -d '{
"username": "testuser",
"password": "secretpass",
"address": "[email protected]",
"ip": "192.168.10.10"
}'
Response for a successful operation:
{
"success": true,
"id": "59708695cdb513ce63340801"
}After you have created an user you can use these credentials to log in to the IMAP server.
Updates the properties of an user. Only specify these fields that you want to be updated.
Parameters
- user (required) is the ID of the user
- name is the updated name for the user
- password is the updated password for the user (do not set if you do not want to change user password)
- forward is an email address to where all messages are forwarded to
- targetUrl is an URL to where all messages are uploaded to
- quota is the maximum storage in bytes allowed for this user
- retention is the default retention time in ms for mailboxes. Messages in Trash and Junk folders have a capped retention time of 30 days.
- language is the language code for the user, eg. "en" or "et". Mailbox names for the default mailboxes (eg. "Trash") depend on the language
- recipients is the maximum number of recipients allowed to send mail to in a 24h window. Requires ZoneMTA with the Wild Duck plugin
- forwards is the maximum number of forwarded emails in a 24h window. Requires ZoneMTA with the Wild Duck plugin
If you want the user to verify existing password before changing anything you can add the following POST field:
- existingPassword is the current password provided by the user for extra verification
Example
Set user quota to 1 kilobyte:
curl -XPUT "http://localhost:8080/users/59467f27535f8f0f067ba8e6" -H 'content-type: application/json' -d '{
"quota": 1024
}'
Response for a successful operation:
{
"success": true
}Authenticates an user
Parameters
- username (required) is the username or one of the email addresses of the user
- password (required) is the password for the user. Can be either master password or an application specific password
- scope is the scope to request for (defaults to "master"). Application specific password can not be used with "master" scope. Allowed scopes are "master", "imap", "pop3", "smtp"
- protocol is the application type this authentication is made from, eg "IMAP" or "API"
- ip is the IP address the request was made from
Response fields
-
success should be
true - id is the id of the authenticated user
- username is the user name of the logged in user (useful if you logged in used)
- scope is the scope this authentication is valid for
-
require2fa if
truethe the user should also provide a 2FA token before the user is allowed to proceed
Example
curl -XPOST "http://localhost:8080/authenticate" -H 'content-type: application/json' -d '{
"username": "testuser",
"password": "amurboxphxvnyqre",
"scope": "pop3",
"ip": "192.168.10.10"
}'
Response for a successful operation:
{
"success": true,
"id": "5971da1754cfdc7f0983b2ec",
"username": "testuser",
"scope": "pop3",
"require2fa": false
}Returns data about authentication related events. This includes also password changes, application specific password changes etc.
Parameters
- user (required) is the ID of the user
- limit is an optional number to limit listing length, defaults to 20
Example
curl "http://localhost:8080/users/5971da1754cfdc7f0983b2ec/authlog"
Response for a successful operation:
{
"success": true,
"total": 1,
"page": 1,
"prev": false,
"next": "/users/5971da1754cfdc7f0983b2ec/authlog?next=eyIkb2lkIjoiNTk3NWY2YTkzNGY3NDNjODk3NWFjOTk0In0&limit=20&page=2",
"results": [
{
"id": "59762d2f9c035be17bbb1fdf",
"action": "create asp",
"asp": "59762d2f9c035be17bbb1fde",
"result": "success",
"ip": "192.168.10.10",
"created": "2017-07-24T17:23:59.041Z"
}
]
}Log entries expire after 30 days.
Wild Duck supports TOTP based 2FA. If 2FA is enabled then users are requested to enter authentication token after successful login. Also, with 2FA enabled, master password can not be used in IMAP, POP3 or SMTP. The user must create an Application Specific Password with a correct scope for email clients using these protocols.
This call prepares the user to support 2FA tokens. If 2FA is already enabled then this call fails.
Parameters
- user (required) is the ID of the user
- issuer is the name to be shown in the Authenticator App
- ip is the IP address the request was made from
Response fields
-
success should be
true - qrcode is the data url for the 2FA QR-code. The user must scan the code and return the token with a PUT call
Example
curl -XPOST "http://localhost:8080/users/5971da1754cfdc7f0983b2ec/2fa" -H 'content-type: application/json' -d '{
"issuer": "testikas",
"ip": "192.168.10.10"
}'
Response for a successful operation:
{
"success": true,
"qrcode": "data:image/png;base64,iVBORw0KGgoAAAANSU..."
}Once 2FA QR code is generated the user must return the token with this call. Once the token is successfully provided then 2FA is enabled for the account.
Parameters
- user (required) is the ID of the user
- token is the 2FA token generated from the QR code
- ip is the IP address the request was made from
Response fields
-
success should be
true
Example
curl -XPUT "http://localhost:8080/users/5971da1754cfdc7f0983b2ec/2fa" -H 'content-type: application/json' -d '{
"token": "455912",
"ip": "192.168.10.10"
}'
Response for a successful operation:
{
"success": true
}Disabling 2FA re-enables master password usage for IMAP, POP3 and SMTP.
Parameters
- user (required) is the ID of the user
- ip is the IP address the request was made from
Response fields
-
success should be
true
Example
curl -XDELETE "http://localhost:8080/users/5971da1754cfdc7f0983b2ec/2fa?ip=192.168.10.10"
Response for a successful operation:
{
"success": true
}Validates a TOTP token against user 2FA settings. This check should be performed when an user authentication response includes request2fa:true
Parameters
- user (required) is the ID of the user
- token (required) is the token to check
- ip is the IP address the request was made from
Response fields
-
success should be
true
Example
curl "http://localhost:8080/users/5971da1754cfdc7f0983b2ec/2fa?token=123456&ip=192.168.10.10"
Response for a successful operation:
{
"success": true
}Application Specific Passwords can be used to allow specific applications to access only specific parts of the user account. For example one password can be used to access IMAP, one for SMTP etc.
Lists all application specific passwords for an user.
Parameters
- user (required) is the ID of the user
Example
curl "http://localhost:8080/users/59467f27535f8f0f067ba8e6/asps"
Response for a successful operation:
{
"success": true,
"results": [
{
"id": "5975d1ac97130ca55afa0c7f",
"description": "OSX Mail App",
"scopes": [
"*"
],
"created": "2017-07-24T10:53:32.136Z"
},
{
"id": "5975f5e5453019c6ebfed3b4",
"description": "Nodemailer",
"scopes": [
"smtp"
],
"created": "2017-07-24T13:28:05.770Z"
}
]
}Creates a new Application Specific Password for an existing user, returns the ID upon success.
Parameters
- user (required) is the ID of the user
- description (required) is the name or description for the new Application Specific Password
- scopes is an array of scopes this password is valid for. Valid scopes are "imap", "pop3", "smtp" or "*" for all ASP supported scopes
- ip is the IP address the request was made from
Example
curl -XPOST "http://localhost:8080/users/5971da1754cfdc7f0983b2ec/asps" -H 'content-type: application/json' -d '{
"description": "Mac OSX Mail Client",
"scopes": ["*"],
"ip": "192.168.10.10"
}'
Response for a successful operation:
{
"success": true,
"id": "59762d2f9c035be17bbb1fde",
"password": "mjxlzydlusadfynn"
}Resulting password should be shown to the client. This password is shown only once so if the user forgets it then the APS should be deleted and replaced with a new one.
Deletes an Application Specific Password
Parameters
- user (required) is the ID of the user
- asp (required) is the ID of the Application Specific Password
- ip is the IP address the request was made from
Example
curl -XDELETE "http://localhost:8080/users/59467f27535f8f0f067ba8e6/asps/59762d2f9c035be17bbb1fde?ip=192.168.10.10"
Response for a successful operation:
{
"success": true
}Manage email addresses
Returns data about existing addresses. Use this endpoint if you want to find an address but do not know to which user it belongs to.
Parameters
- query is an optional string to filter addresses (partial match), by default all addresses are listed
- limit is an optional number to limit listing length, defaults to 20
Example
curl "http://localhost:8080/addresses?query=testuser01"
Response for a successful operation:
{
"success": true,
"query": "testuser01",
"total": 1,
"page": 1,
"prev": false,
"next": false,
"results": [
{
"id": "5970860fcdb513ce633407a8",
"address": "[email protected]",
"user": "5970860fcdb513ce633407a1"
}
]
}Lists all registered email addresses for an user.
Parameters
- user (required) is the ID of the user
Example
curl "http://localhost:8080/users/59467f27535f8f0f067ba8e6/addresses"
Response for a successful operation:
{
"success": true,
"results": [
{
"id": "596c9c37ef2213165daadc6b",
"address": "[email protected]",
"main": true,
"created": "2017-07-17T11:15:03.841Z"
},
{
"id": "596c9dd31b201716e764efc2",
"address": "[email protected]",
"main": false,
"created": "2017-07-17T11:21:55.960Z"
}
]
}Returns data about a specific address.
Parameters
- user (required) is the ID of the user
- address (required) is the ID of the address
Example
curl "http://localhost:8080/users/59467f27535f8f0f067ba8e6/addresses/596c9c37ef2213165daadc6b"
Response for a successful operation:
{
"success": true,
"id": "596c9c37ef2213165daadc6b",
"address": "[email protected]",
"main": true,
"created": "2017-07-17T11:15:03.841Z"
}Creates a new email address alias for an existing user, returns the ID upon success.
Parameters
- user (required) is the ID of the user
- address (required) is the email address to use as an alias for this user. You can also use internationalized email addresses like андрис@уайлддак.орг.
- main indicates that this is the default address for that user (defaults to false)
Example
curl -XPOST "http://localhost:8080/users/59467f27535f8f0f067ba8e6/addresses" -H 'content-type: application/json' -d '{
"address": "[email protected]"
}'
Response for a successful operation:
{
"success": true,
"id": "596c9dd31b201716e764efc2"
}After you have registered a new address then LMTP maildrop server starts accepting mail for it and stores messages to the users mailbox.
Updates the properties of an address. Currently, only main can be updated.
Parameters
- user (required) is the ID of the user
- address (required) is the ID of the address
- main must be true. Indicates that this is the default address for that user
Example
curl -XPUT "http://localhost:8080/users/59467f27535f8f0f067ba8e6/addresses/596c9dd31b201716e764efc2" -H 'content-type: application/json' -d '{
"main": true
}'
Response for a successful operation:
{
"success": true
}Deletes an email address alias from an existing user.
Parameters
- user (required) is the ID of the user
- address (required) is the ID of the address
Example
curl -XDELETE "http://localhost:8080/users/59467f27535f8f0f067ba8e6/addresses/596c9dd31b201716e764efc2"
Response for a successful operation:
{
"success": true
}Manage user mailboxes
Lists existing mailboxes for an user
Parameters
- user (required) is the ID of the user
- counters is an optional GET argument to include counters (total messages, unseen messages) in listing results. Not recommended if you have a large list as checking every counter can be expensive operation.
Example
curl "http://localhost:8080/users/59467f27535f8f0f067ba8e6/mailboxes"
Response for a successful operation:
{
"success": true,
"results": [
{
"id": "597089f1b3378cd394611284",
"name": "INBOX",
"path": "INBOX",
"specialUse": null,
"modifyIndex": 71,
"subscribed": true
},
{
"id": "597089f1b3378cd394611289",
"name": "Archive",
"path": "Archive",
"specialUse": "\\Archive",
"modifyIndex": 0,
"subscribed": true
},
{
"id": "597089f1b3378cd394611287",
"name": "Drafts",
"path": "Drafts",
"specialUse": "\\Drafts",
"modifyIndex": 0,
"subscribed": true
}
]
}List mailboxes with counters
curl "http://localhost:8080/users/59467f27535f8f0f067ba8e6/mailboxes?counters=true"
Response for a successful operation:
{
"success": true,
"mailboxes": [
{
"id": "597089f1b3378cd394611284",
"name": "INBOX",
"path": "INBOX",
"specialUse": null,
"modifyIndex": 71,
"subscribed": true,
"total": 33,
"unseen": 8
},
{
"id": "597089f1b3378cd394611289",
"name": "Archive",
"path": "Archive",
"specialUse": "\\Archive",
"modifyIndex": 0,
"subscribed": true,
"total": 0,
"unseen": 0
},
{
"id": "597089f1b3378cd394611287",
"name": "Drafts",
"path": "Drafts",
"specialUse": "\\Drafts",
"modifyIndex": 0,
"subscribed": true,
"total": 0,
"unseen": 0
}
]
}Returns data about a specific address.
Parameters
- user (required) is the ID of the user
- mailbox (required) is the ID of the mailbox
Example
curl "http://localhost:8080/users/59467f27535f8f0f067ba8e6/mailboxes/597089f1b3378cd394611284"
Response for a successful operation:
{
"success": true,
"id": "597089f1b3378cd394611284",
"name": "INBOX",
"path": "INBOX",
"specialUse": null,
"modifyIndex": 71,
"subscribed": true,
"total": 33,
"unseen": 8
}Creates a new mailbox for an existing user account, returns the ID upon success.
Parameters
- user (required) is the ID of the user
- path (required) is the mailbox path with slashes as folder separators. Parent folder does not have to exist. Using unicode characters is allowed.
- retention optional retention time in milliseconds that applies to messages in that mailbox
Example
curl -XPOST "http://localhost:8080/users/59467f27535f8f0f067ba8e6/mailboxes" -H 'content-type: application/json' -d '{
"path": "My New mailbox"
}'
or as a subfolder
curl -XPOST "http://localhost:8080/users/59467f27535f8f0f067ba8e6/mailboxes" -H 'content-type: application/json' -d '{
"path": "Some parent/Subfolder/My New mailbox"
}'
Response for a successful operation:
{
"success": true,
"id": "596c9dd31b201716e764efc2"
}Updates the properties of a mailbox.
Parameters
- user (required) is the ID of the user
- mailbox (required) is the ID of the mailbox
- path is the optional new mailbox path if you want to rename the mailbox. INBOX can not be renamed.
- retention is the optional new retention time. Changing retention time applies only to new messages. Existing messages expire once the original retention time is reached
Example
curl -XPUT "http://localhost:8080/users/59467f27535f8f0f067ba8e6/mailboxes/596c9dd31b201716e764efc2" -H 'content-type: application/json' -d '{
"path": "New Mailbox Name"
}'
Response for a successful operation:
{
"success": true
}Deletes a mailbox. Only user made mailboxes can be deleted. Special mailboxes (INBOX, Trash etc) can not be deleted.
Parameters
- user (required) is the ID of the user
- mailbox (required) is the ID of the mailbox
Example
curl -XDELETE "http://localhost:8080/users/59467f27535f8f0f067ba8e6/mailboxes/596c9dd31b201716e764efc2"
Response for a successful operation:
{
"success": true
}Manage messages in a mailbox
Lists existing messages in a mailbox
Parameters
- user (required) is the ID of the user
- mailbox (required) is the ID of the mailbox
- order optional message ordering, either "asc" or "desc". Defaults to "desc" (newer first)
Example
curl "http://localhost:8080/users/59467f27535f8f0f067ba8e6/mailboxes/596c9dd31b201716e764efc2/messages"
Response for a successful operation:
{
"success": true,
"total": 1,
"page": 1,
"prev": false,
"next": false,
"specialUse": null,
"results": [
{
"id": "5971da5754cfdc7f0983b8c0:444",
"mailbox": "59467f27535f8f0f067ba8e6",
"thread": "5971da7754cfdc7f0983bbde",
"from": {
"address": "[email protected]",
"name": "Sender Name"
},
"subject": "Subject line",
"date": "2011-11-02T19:19:08.000Z",
"intro": "Beginning text in the message…",
"attachments": false,
"seen": true,
"deleted": false,
"flagged": false,
"draft": false
}
]
}Search user messages. This is a account wide search function that searches from every folder except Trash and Junk.
Parameters
- user (required) is the ID of the user
- mailbox (required) is the ID of the mailbox
- query query string to search for
Example
curl "http://localhost:8080/users/59467f27535f8f0f067ba8e6/search?query=myname"
Response for a successful operation:
{
"success": true,
"query": "myname",
"total": 1,
"page": 1,
"prev": false,
"next": false,
"results": [
{
"id": "5971da5754cfdc7f0983b8c0:444",
"mailbox": "59467f27535f8f0f067ba8e6",
"thread": "5971da7754cfdc7f0983bbde",
"from": {
"address": "[email protected]",
"name": "Sender Name"
},
"subject": "Subject line",
"date": "2011-11-02T19:19:08.000Z",
"intro": "Beginning text in the message…",
"attachments": false,
"seen": true,
"deleted": false,
"flagged": false,
"draft": false
}
]
}The search uses MongoDB fulltext index, see MongoDB docs for explanation how to use it.
Returns data about a specific address.
Parameters
- user (required) is the ID of the user
- mailbox (required) is the ID of the mailbox
- message (required) is the ID of the message
Example
curl "http://localhost:8080/users/59467f27535f8f0f067ba8e6/mailboxes/596c9dd31b201716e764efc2/messages/5971da5754cfdc7f0983b8c0:444"
Response for a successful operation:
{
"success": true,
"id": "5971da5754cfdc7f0983b8c0:444",
"from": {
"address": "[email protected]",
"name": "Sender Name"
},
"to": [
{
"address": "[email protected]",
"name": "Test User"
}
],
"subject": "Subject line",
"messageId": "<[email protected]>",
"date": "2011-11-02T19:19:08.000Z",
"seen": true,
"deleted": false,
"flagged": false,
"draft": false,
"html": [
"Notice that the HTML content is an array of HTML strings"
],
"attachments": []
}Updates the properties of a message or move the message to another mailbox.
Parameters
- user (required) is the ID of the user
- mailbox (required) is the ID of the mailbox
- message (required) is the ID of the message
- newMailbox is the ID of the destination mailbox if you want to move the message
- seen is a boolean to mark message as seen or unseen
- flagged is a boolean to mark message as flagged or not
- draft is a boolean to mark message as a draft or not
- deleted is a boolean to mark message as deleted or not. This value is used by IMAP clients to indicate that a message should be deleted in the future
-
expires is either a date/timestamp to autodelete the message at given time or
falseif you want to clear the expiration date. Message is not deleted exactly on the expire time, it is only marked to be deleted and it is removed after the garbage collector process steps in.
Example
curl -XPUT "http://localhost:8080/users/59467f27535f8f0f067ba8e6/mailboxes/596c9dd31b201716e764efc2/messages/5971da5754cfdc7f0983b8c0:444" -H 'content-type: application/json' -d '{
"seen": true
}'
Response for a successful operation:
{
"success": true
}Deletes a message from mailbox. This deletes the message entirely, in most cases consider the message to the Trash folder instead.
Parameters
- user (required) is the ID of the user
- mailbox (required) is the ID of the mailbox
- message (required) is the ID of the message
Example
curl -XDELETE "http://localhost:8080/users/5971da1754cfdc7f0983b2ec/mailboxes/5971da1754cfdc7f0983b2ed/messages/5971da5754cfdc7f0983b8c0:444"
Response for a successful operation:
{
"success": true
}Returns raw message source.
Parameters
- user (required) is the ID of the user
- mailbox (required) is the ID of the mailbox
- message (required) is the ID of the message
Example
curl "http://localhost:8080/users/59467f27535f8f0f067ba8e6/mailboxes/596c9dd31b201716e764efc2/messages/5971da5754cfdc7f0983b8c0:444/message.eml"
Response for a successful operation:
HTTP/1.1 200 OK
Server: Wild Duck API
Content-Type: message/rfc822
Date: Fri, 21 Jul 2017 19:11:04 GMT
Connection: keep-alive
Transfer-Encoding: chunked
Delivered-To: [email protected]
Received: .....
<rfc822 formatted message>
Returns data about a specific address.
Parameters
- user (required) is the ID of the user
- mailbox (required) is the ID of the mailbox
- message (required) is the ID of the message
- attachment (required) is the ID of the attachment
Example
curl "http://localhost:8080/users/59467f27535f8f0f067ba8e6/mailboxes/596c9dd31b201716e764efc2/messages/5971da5754cfdc7f0983b8c0:444/attachments/ATT00001"
Response for a successful operation:
HTTP/1.1 200 OK
Server: Wild Duck API
Content-Type: image/png
Date: Fri, 21 Jul 2017 18:39:05 GMT
Connection: keep-alive
Transfer-Encoding: chunked
<attachment contents>
Recalculates used storage for an user. Use this when it seems that quota counters for an user do not match with reality.
Parameters
- user (required) is the ID of the user
Example
curl -XPOST "http://localhost:8080/users/59467f27535f8f0f067ba8e6/quota/reset" -H 'content-type: application/json' -d '{}'
Response for a successful operation:
{
"success":true,
"storageUsed": 128
}Be aware though that this method is not atomic and should be done only if quota counters are way off.
Get user related events as an Event Source stream
Streams changes in user account as EventSource stream
Parameters
- user (required) is the ID of the user
Example
curl "http://localhost:8080/users/59467f27535f8f0f067ba8e6/updates"
Response stream:
data: {"command":"EXISTS", "message":"596e0703f0bdd512aeac3600", "mailbox":"596c9c37ef2213165daadc65",...}
id: 596e0703f0bdd512aeac3605
data: {"command":"CREATE","mailbox":"596e09853f845a14f3620b5c","name":"My Mail",...}
id: 596e09853f845a14f3620b5d
First entry in the event stream indicates that a message with id 596e0703f0bdd512aeac3600 was added to mailbox 596c9c37ef2213165daadc65, second entry indicates that a new mailbox called "My Mail" with id 596e09853f845a14f3620b5c was created.
Be aware though that this connection needs to be properly closed if you do not want to end up with memory leaks.
You can see a demo of catching user events when navigating to http://localhost:8080/public/ (assuming localhost:8080 is your API host).
Demo video for HTTP push
