API:E-mail

This page is part of the MediaWiki API documentation.

Language:	English

MediaWiki API

Quick overview:

• Quick start guide
• FAQ
  • Etiquette and usage limits
• Tutorial
• Formats
• Error reporting
• Restricting usage
• Authentication
  • Login
  • Logout
• Queries
  • Meta information
  • Properties
  • Lists
• Search suggestions
• Expanding templates and rendering
• Purging pages' caches
• Parameter information
• Changing wiki content
  • Create and edit pages
  • Move pages
  • Rollback
  • Delete pages
  • Restore deleted revisions
  • (Un)protect pages
  • (Un)block users
  • (Un)watch pages
  • Send e-mail
  • Patrol changes
  • Import pages
  • Change user group membership
  • Upload files
  • User options
• Watchlist feed
• Extensions
• Using the API in MediaWiki and extensions
• Miscellaneous
• Implementation
• Client code

MediaWiki version:

1.14

Token

To send an e-mail, an e-mail token is required. This token is equal to the edit token and the same for all recipients, but changes at every login. An e-mail token can be obtained as follows: Obtaining an e-mail token

api.php ? action=query & prop=info & intoken=email & titles=User:Catrope

<?xml version="1.0" encoding="utf-8"?>
<api>
  <query>
    <pages>
      <page
        pageid="1"
        ns="2"
        title="User:Catrope"
        touched="2007-09-03T20:32:21Z"
        lastrevid="20"
        counter="20"
        length="470"
        emailtoken="58b54e0bab4a1d3fd3f7653af38e75cb+\" 
      />
    </pages>
  </query>
</api>

Sending e-mail to users

You can send e-mail to users who have a confirmed e-mail address with action=emailuser. Sending email is subject to rate limits.

Parameters

• target: User to send e-mail to
• subject: The subject of the message
• text: The message
• token: The token obtained in the previous request. Take care to encode the + as %2B
• ccme: If set, a copy of the e-mail will be sent to you

Examples

Note: In this example, all parameters are passed in a GET request just for the sake of simplicity. However, action=emailuser requires POST requests; GET requests will cause an error.

Sending an e-mail to User:Catrope

api.php ? action=emailuser & target=Catrope & subject=Hi & text=Just%20wanted%20to%20say%20hi & token=58b54e0bab4a1d3fd3f7653af38e75cb+\

<?xml version="1.0" encoding="utf-8"?>
<api>
  <emailuser result="Success" />
</api>

Possible errors

In addition to the usual stuff:

• code: cantsend
  • info: You're not logged in or you don't have a confirmed e-mail address, so you can't send e-mail
• code: blockedfrommail
  • info: You have been blocked from sending e-mail
• code: usermaildisabled
  • info: User email has been disabled
• code: notarget
  • info: You have not specified a valid target for this action
• code: noemail
  • info: The user has not specified a valid e-mail address, or has chosen not to receive e-mail from other users

Checking emailable status

Before trying to send an email, it is recommended to check if the user is emailable first. To do this, you can execute a list query on the user (or several users at once). Here is an example using Ajax:

$.ajax({
  url: wgScriptPath + '/api.php?',
  data: 'action=query&list=users&ususers='+encodeURIComponent(wgTitle)+'&usprop=emailable&format=json',
  dataType: 'json',
  success: function( data ) {
    if ( typeof data.query.users[0]['emailable'] !== 'undefined' ) {
      emailable = true;
    } else {
      emailable = false;
    }
  }
});

If you are testing from a client-side script, it is also possible to simply check for the existence of the t-emailuser list item:

emailable = $('#t-emailuser').length ? true : false;