Writing basic AutoModerator rules

This page is intended as an introduction to writing AutoModerator rules. If you are looking for complete information about AutoModerator's capabilities, see the full documentation page instead.

Important knowledge

The following information is extremely important and should be read and understood fully before proceeding:

  • Rules must be separated by a line consisting entirely and exactly of ---. 3 hyphens, without any spaces before them.
  • Rules that can cause the subject to be removed are checked first. Because of this, you should expect removal rules to take priority over all other types of rules.
  • By default, rules that can cause the subject to be removed or reported will not be applied to moderators' posts. This behavior can be overridden, but keep it in mind, especially when trying to test.
  • AutoModerator tries to avoid contradicting other mods' actions. It will not remove a post if it has already been approved by another moderator, or approve it if it has been removed by one.

The pieces of an AutoModerator rule

An AutoModerator rule must consist of one or more checks (conditions that the comment or submission must meet) and one or more actions (things that will be performed on any posts that meet the conditions). Both checks and actions are defined by writing a line that has the name of the check or the action, followed by a colon, and then the value to set it to. For example, the line to define the action of removing a post looks like this:

action: remove

This sets the value of action for that rule to remove. A rule is made up by defining all of its checks and actions separately just like this. For example, here is a basic, complete rule to remove any submission that has the word "disallowed" in its title. Note that AutoModerator is not case-sensitive by default, so this rule will also apply to submissions with "Disallowed", "DISALLOWED", etc. in their titles:

title: disallowed
action: remove

That's it. All AutoModerator rules are simply a combination of checks and actions, but some very complex rules can be built up from these pieces.

In general, if you define multiple different checks on a rule, all of them must be satisfied in order to cause the actions to be performed. For example, here is a similar rule with two separate checks:

title: disallowed
action: remove

Now a submission with "disallowed" in its title will only be removed if it is also a link to YouTube. If it has "disallowed" in the title but goes to any other domain at all, it will not be removed because both of the conditions were not satisfied. If you instead want to remove a post if the word "disallowed" is in its title or it is a link to YouTube, that should be written as two separate rules instead (notice the --- line separating the two rules):

title: disallowed
action: remove
action: remove

Checking for any item from a list of possibilities

Of course, most rules do not apply to only a single word or domain. It is very common to write rules similar to "if the title contains any of these words...", so AutoModerator includes a way to define a list of possibilities, where the rule will be applied if any of the possibilities are found. For example, here is a rule that will set a submission's flair text to "Primary Color" for any submission with any of "red", "green", or "blue" in its title:

title: [red, green, blue]
set_flair: Primary Color

To define a list of items, surround the entire list with square brackets, and separate items with commas.

Reverse checks / "must not match"

Sometimes it is useful to be able to do a "reverse check", where instead of looking for the presence of something in particular, you want to check whether something is NOT present. For example, if a sub required every submission to be from YouTube, they would want a rule to remove any submission that is from any other domain. A check is reversed by putting a tilde ~ in front of it, so the rule for a YouTube-only sub would be something like:

~domain: [,]
action: remove

Author checks

In addition to checking for conditions to be satisfied by comments or submissions themselves, you can also set conditions on the author of them. The simplest thing to check is the author's username. For example, say that your sub has two users named OfficialGuy and AnotherOfficialUser, and you want to give their submissions flair saying "Official Post" whenever they submit something. The rule would be:

author: [OfficialGuy, AnotherOfficialUser]
set_flair: Official Post

There are also various other author checks supported related to characteristics of the user. For example, if you have a sub that has trouble with new accounts posting their blogs, you could write a rule that will remove any submission from tumblr or blogspot from accounts less than a day old:

domain: [,]
    account_age: < 1 day
action: remove

Notice that the account_age: setting is indented further than author: is. This is because the account_age check must be done "inside" the author check. For more information about what is possible with author checks, please see the section of the official documentation listing the other available ones.

Checking for type

One other check that can be extremely useful is to be able to specify which type of post you want a rule to apply to. For example, this rule would automatically remove all link submissions from users that have less than 5 comment karma, but will not affect any text submissions or comments they make:

type: link submission
    comment_karma: < 5
action: remove

Posting comments or sending modmail

In addition to directly taking actions on posts like approving, removing or reporting them or setting flair, one of the most common needs is to have AutoModerator leave a comment in response or send a modmail. This is done by simply defining comment: or modmail: as part of the rule. For example:

domain: [,]
action: remove
comment: Sorry, your submission has been automatically removed. Videos are not allowed in this sub.

Or something like:

title: [this sub, meta, mods, moderators]
modmail: This submission seems to be about the sub, a mod should probably check on it.

Note that a link to the post will automatically be included in a modmail, so the modmail from the above rule would include a link to the submission in question.

Multi-line comments and modmails are also supported. To define text across multiple lines, the first line should be only |, and then all the lines to include in the text should be indented below, similar to putting age or karma checks inside author:. Here is a multi-line comment:

domain: [,]
comment: |
    Sorry, your submission has been automatically removed.

    This sub does not allow videos to be posted.

    You might want to consider posting to /r/videos instead.
action: remove

There are also a number of "placeholders" that you can insert into comments and messages that will be replaced by the relevant information from the post. Here is an improvement of the modmail rule above that includes more information:

title: [this sub, meta, mods, moderators]
modmail: |
    A submission that appears to be about the sub has been made by /u/{{author}}.

    **Title:** {{title}}

When this rule matches a submission, {{author}} and {{title}} will be replaced in the modmail by the author's username and the post's title respectively.

revision by d3rr— view source