API:Emailuser

MediaWiki version:

≥ 1.14

Email a user.

Token

To send an email, an email token is required. This token is equal to the edit token and the same for all recipients, but changes at every login. Email tokens can be obtained via action=tokens with type=email (MW 1.20+), or by using the following method:

Obtaining an email token

api.php?action=query&prop=info&intoken=email&titles=User:Catrope [try in ApiSandbox]

Result
<?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 email to users

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

Parameters

target: User to send email 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 email 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 email to User:Catrope

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

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

Possible errors

In addition to the usual stuff:

Code	Info
cantsend	You're not logged in or you don't have a confirmed email address, so you can't send email
blockedfrommail	You have been blocked from sending email
usermaildisabled	User email has been disabled
notarget	You have not specified a valid target for this action
noemail	The user has not specified a valid email address, or has chosen not to receive email 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:

new mw.Api().get( {
  action: 'query',
  list: 'users',
  ususers: mw.config.get( 'wgTitle' ),
  usprop: 'emailable',
  rawcontinue: ''
} ).done( function( getEmailable ) {
  alert( ( getEmailable.query.users[ 0 ][ 'emailable' ] !== undefined ) ? 'emailable' : 'not emailable' );
} );

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;

action=emailuser

(main | emailuser)

• This module requires read rights.
• This module requires write rights.
• This module only accepts POST requests.
• Source: MediaWiki
• License: GPL-2.0-or-later

Email a user.

• https://www.mediawiki.org/wiki/Special:MyLanguage/API:Email

Specific parameters:

Other general parameters are available.

target

User to send the email to.

This parameter is required.

subject

Subject header.

This parameter is required.

text

Email body.

This parameter is required.

ccme

Send a copy of this mail to me.

Type: boolean (details)

token

A "csrf" token retrieved from action=query&meta=tokens

This parameter is required.

Example:

Send an email to the user WikiSysop with the text Content.

api.php?action=emailuser&target=WikiSysop&text=Content&token=123ABC [open in sandbox]