1. Home
  2. Knowledge Base
  3. Management
  4. The tellmail command line utility

The tellmail command line utility

tellmail is a command line utility that allows you to perform some administrative tasks with SurgeMail such as adding users and domains to locating a users mailbox. To use tellmail you just need to type tellmail at the shell or command prompt. On Windows you can get to the command prompt by going left clicking on the start button, then program files, then accessories then command prompt.

C:\>tellmail <command>

All commands are preceeded by typing tellmail

General tellmail commands


Misc. tellmail commands


User commands

path <user@domain>
add_user <user@domain>
delete_user <user@domain>
change_pass <user@domain> <password>
add_user_alias <user> <alias>
delete_user_alias <user> <alias>
add_domain <domain>
delete_domain <domain>
clear_cache [user@domain]

logout <user@domain>
expire_user <user@domain> <days> <bytes>
set_authfield fieldname file.txt [apply]
find_user <domain> <field_name> <field_value>
user_send_max <user@domain>
add_member <list> <user@domain>
add_rules <file>
list_rcpt <domain> [type]

Quota Commands

quota <user@domain> - Displays the users quota
quota_rebuild <user@domain> - Rebuilds user's quota.
quota_domain <domain> - Displays how much data the domain is currently using.
quota_rebuild_domain <domain> - Rebuilds the quota usage for this domain
quota_set_domain <domain> <size> - Sets the used disk for the specified domain
quota_resetall - Rebuilds all quotas for all users.
quota_set <user@domain> <amount> - sets the users quota.

Migration commands

imap_import <localuser@localdomain> <oldimaphost> <olduser> <oldpass> <delete|keep> <create|nocreate>
pstat_delete user@xyz.com - Forget about the user so it may re-import the user (dependent on other settings)

License commands

activate<registration> [email address]
deactivate<registration> [email address]


resync_folder <arbitraryfolder>

Ini settings

The following commands let you show or set global or domain level settings. In the case of multi value settings you can use the clear_domain command to delete all of the settings before adding new ones.

tellmail set_global setting value
tellmail show_global setting
tellmail set_domain domain.name setting value
tellmail show_domain domain.name setting
tellmail clear_domain domain.name setting


Lists the commands you case use and a brief description


This gives you a ton of information on the server.


This allows you reload SurgeMail without having to stop and restart it which means it won't interrupt users that are currently online. Great if you have edited surgemail.ini manually and need to activate your changes without disrupting service.


This simply tells SurgeMail to shutdown.


This displays the current delivery queue.

path <user@domain>

This allows you to find where a users mailbox is stored on the disk.

C:\>tellmail path stu@catch.netwin.co.nz

add_user <user@domain>

This allows you to add users easily to SurgeMail.

delete_user <user@domain>

This allows you to delete users from SurgeMail. The deletion process is as follows.

  • Deletes user from authentication database
  • Removes cache entry
  • Decreases registration count
  • Decreases user count for domain
  • Removes WebMail files (tells webmail to)
  • Removes SurgeMail files (users mail)
  • Removes aliases
  • Removes mailing list subscriptions
  • Records them in users_YYYYMMDD.rec

change_pass <user@domain> <pass>

This allows you to change users passwords easily.

add_user_alias <user> <alias>

This allows you to add aliases for users.

delete_user_alias <user> <alias>

This allows you to delete aliases for users.

add_domain <domain>

Adds a domain to SurgeMail. This command makes use of the domain_defaults.txt file specified here.

delete_domain <domain>

Deletes a domain from SurgeMail.

clear_cache [user@domain]

This allows you to clear SurgeMail's authentication cache.
tellmail clear_cache - With no argument it will clear the entire cache.
tellmail clear_cache test@localdomain - This will clear only this users cache out
tellmail clear_cache *@domain2.com - Clears the cache for all users at domain2.com

quota <user@domain>

Displays the users current disk usage and their allowed quota.

logout <user@domain>

This will logout a user that is currently connected to on IMAP or POP you can see the current locks by using the tellmail showlocks command

tellmail logout stu@blah.com


This shows the current software locks used by IMAP and POP in SurgeMail. When a user logs into POP or IMAP SurgeMail creates a lock for that user to prevent multiple connections to the same account.


tellmail showlocks
Lock (catch.netwin.co.nz#stu#_) n=1 f=0 locktype=pop thid=2332


This starts the expire process.


Gives the status on the expire process.

expire_user <user@domain> <days> <bytes>

This expires mail in the specified users INBOX, and optionally Trash folders based on the specified criteria, you may specify an age in days and/or a max size in bytes, any message exceeding these will be expired.

find_user <domain> <field name > <field value >

This lets you search for a user or users that match the criteria you have set.


To get a list of accounts of a certain status:
tellmail find_user foo.com mailstatus suspended
tellmail find_user foo.com mailstatus payup
tellmail find_user foo.com mailstatus closed

To find out who is using friends
tellmail find_user foo.com friends true

To find users in a certain group
tellmail find_user foo.com mailaccess groupname

set_authfield fieldname file.txt [apply]

This allows you to apply new authent values for one field based on the text file file.txt and fieldname the name of the field to change. Without [apply] flag this is run in preview mode to see what changes to the database would be made and run with [apply] flag to actually make the changes.

where file.txt contains user, new value pairs

tellmail set_authfield quota newvalues.txt

Processing file (a.a) PREVIEWING CHANGES ...
2 records updated, 0 records did not exist
Original nwauth records stored in pre.txt and updated records in post.txt for review

user_send_max <user@domain>

Reports the number of emails the user has sent in the last 24 hour period.

add_member <list> <user@domain>

Adds the specified email to the specified mailing list.

add_rules <file>

Reads <file>, expects lines formatted:


where "email" is the users email address i.e. user@domain.com and "rule" is a user exception rule formatted as expected in the users friend.rul file (create some rules for a user to discover the format, it can be different for different rules and we may change or extend it in future).

This command will not add duplicate rules. This command will only add rules for existing users.


scan aliases.txt, make domuser.newdat


scans domuser.dat, make aliases.txt


Attempts to list all valid receipt addresses for the server. Can be run as:

tellmail list_rcpt
tellmail list_rcpt domain.name
tellmail list_rcpt domain.name [redirect|lists|alias|blog|misc]

The first gets all receipts.
The next gets only those for the specified domain.
The last gets only those for the specified domain and type.

imap_import <localuser@localdomain> <oldimaphost> <olduser> <oldpass> <delete|keep> <create|nocreate>

You can use this command to import users from another serverm this is for importing imap accounts.

  1. The username and domain to which the account will be created in surgemail
  2. The ip of the server you are migrating the account from
  3. The login name of the account on the server you are migrating from.
  4. The accounts password on the server you are migrating from
  5. Whether you want to delete or keep the messages on the old server
  6. Whether you want the account created on the surgemail server, unless you have already created the account this must be create.


old server:
old user account: fred
old account password: test
username and domain to create on surgemail: fred@mydomain.com

tellmail fred@mydomain.com fred test keep create

activate <registration> [email address]

This tells SurgeMail to contact the netwinsite.com database and activate your SurgeMail server.

deactivate <registration> [email address]

This tells SurgeMail to deactivate SurgeMail. You should do this if you are going to move SurgeMail to a new machine and then can reactivate on the new machine.


This tells SurgeMail to send the config file to the other mirror, you would run this on the machine that has the data you want transferred.


This tells SurgeMail to resend missing files to the slave, this uses a separate thread.
You run this on the machine that has the extra data, if both machines for some reason have data that each other doesn't have it is safe to run this command on both slave and master. This command only sends data the other machine does NOT have, so is considered a very safe command.


This resends NWAuth to the other machine, usually run on the master, but if the master had a disk crash and lost NWAuth you would run this on the slave.


This resends the surgemail.ini to the other machine, usually run on the master, but if the master had a disk crash and lost it's config you would run this on the slave. This is required every time you enable g_mirror_config, i.e. add it, or go from FALSE to TRUE on either machine.


This command creates emtpy folders on the destination server, normally the mirroring only sends messages so doesn't create empty imap folders.


surgeplus is used for doing various SurgePlus commands. use "tellmail surgeplus" for a full list of SurgePlus commands. Some common surgeplus commands are

  • tellmail surgeplus status - View current surgeplus status
  • tellmail surgeplus rebuild - Delete cached client downloads so they will be rebuilt next time a user tries to download them. Useful if you have customized a SurgePlus image file.
  • tellmail surgeplus activate (24-digit-license-key) - Tell SurgeMail to use your new SurgePlus license key.
  • tellmail surgeplus download - Download the latest SurgePlus beta and release versions from netwinsite.com to make available to your users.
  • tellmail surgeplus reload - Reloads and SurgePlus config files from disk.


You should only run this command if you manually change Aspam files.

g_relay_allow_ip <ip>

This allows you to check if an IP is allowed to relay or not.

eg tellmail g_relay_allow_ip


This command will stop SurgeMail from sending any mail out, instead it will just queue it until a tellmail resume command is issued.


This command will make SurgeMail start sending the queue out again after it has been placed in suspend mode by the tellmail suspend command.


This command will make SurgeMail generate a new surgehost.ini file for use with webmail. It will run through all the domains in surgemail and update surgehost.ini for each domain.

report_unused (or report_used)

tellmail report_unused DAYS, gives a report showing inactive accounts that have not been logged into for the specified number of days.

Was this article helpful?

Related Articles