Jump to content
MediaWiki

API:Emailuser

From mediawiki.org
This page is part of the MediaWiki Action API documentation.
MediaWiki Action API
Basics
Authentication
Accounts and Users
Page Operations
Search
Developer Utilities
Tutorials
v · d · e
Emailuser
Email a user.
This module cannot be used as a generator.
Prefix none
Required rights sendemail
Post only? Yes
Generated help Current
Version added
≥ 1.13


API documentation

[edit ]
The following documentation is the output of Special:ApiHelp/emailuser, automatically generated by the pre-release version of MediaWiki that is running on this site (MediaWiki.org).

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.

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]


Token

[edit ]

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=query&meta=tokens , or by using the following method:

Obtaining an email token
Result
{
"batchcomplete":"",
"query":{
"tokens":{
"csrftoken":"7773cbfff263682c97ffc74b8672cbf25a5e0045+\\"
}
}
}

Sending email to users

[edit ]

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

Parameters

[edit ]
  • 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

[edit ]
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
Result
<?xml version="1.0" encoding="utf-8"?>
<api>
<emailuserresult="Success"/>
</api>

Sample code

[edit ]

Python

[edit ]
#!/usr/bin/python3
"""
 send_email.py
 MediaWiki API Demos
 Demo of `Emailuser` module: sending POST request to send email to wiki user
 Author: Jayprakash12345
 MIT license
"""
import requests
S = requests.Session()
URL = "https://test.wikipedia.org/w/api.php"
# Step 1: GET request to fetch login token
PARAMS_0 = {
 "action": "query",
 "meta": "tokens",
 "type": "login",
 "format": "json"
}
R = S.get(url=URL, params=PARAMS_0)
DATA = R.json()
LOGIN_TOKEN = DATA['query']['tokens']['logintoken']
# Step 2: POST request to log in. Use of main account for login is not
# supported. Obtain credentials via Special:BotPasswords
# (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
PARAMS_1 = {
 "action": "login",
 "lgname": "your_bot_username",
 "lgpassword": "your_bot_password",
 "lgtoken": LOGIN_TOKEN,
 "format": "json"
}
R = S.post(URL, data=PARAMS_1)
# Step 3: GET request to fetch Email token
PARAMS_2 = {
 "action": "query",
 "meta": "tokens",
 "format": "json"
}
R = S.get(url=URL, params=PARAMS_2)
DATA = R.json()
EMAIL_TOKEN = DATA['query']['tokens']['csrftoken']
# Step 4: POST request to send an email
PARAMS_3 = {
 "action": "emailuser",
 "target": "Test",
 "subject": "Hi",
 "text": "Just wanted to say hi",
 "token": EMAIL_TOKEN,
 "format": "json"
}
R = S.post(URL, data=PARAMS_3)
DATA = R.text
print(DATA)

PHP

[edit ]
<?php
/*
 send_email.php
 MediaWiki API Demos
	Demo of `Emailuser` module: sending POST request to send email to wiki user
 MIT license
*/
$endPoint = "https://en.wikipedia.org/w/api.php";
$login_Token = getLoginToken(); // Step 1
loginRequest( $login_Token ); // Step 2
$csrf_Token = getCSRFToken(); // Step 3
sendemail( $csrf_Token ); // Step 4
// Step 1: GET request to fetch login token
function getLoginToken() {
	global $endPoint;
	$params1 = [
		"action" => "query",
		"meta" => "tokens",
		"type" => "login",
		"format" => "json"
	];
	$url = $endPoint . "?" . http_build_query( $params1 );
	$ch = curl_init( $url );
	curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
	curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
	curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
	$output = curl_exec( $ch );
	curl_close( $ch );
	$result = json_decode( $output, true );
	return $result["query"]["tokens"]["logintoken"];
}
// Step 2: POST request to log in. Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
function loginRequest( $logintoken ) {
	global $endPoint;
	$params2 = [
		"action" => "login",
		"lgname" => "your_bot_username",
		"lgpassword" => "your_bot_password",
		"lgtoken" => $logintoken,
		"format" => "json"
	];
	$ch = curl_init();
	curl_setopt( $ch, CURLOPT_URL, $endPoint );
	curl_setopt( $ch, CURLOPT_POST, true );
	curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query( $params2 ) );
	curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
	curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
	curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
	$output = curl_exec( $ch );
	curl_close( $ch );
}
// Step 3: GET request to fetch CSRF token
function getCSRFToken() {
	global $endPoint;
	$params3 = [
		"action" => "query",
		"meta" => "tokens",
		"format" => "json"
	];
	$url = $endPoint . "?" . http_build_query( $params3 );
	$ch = curl_init( $url );
	curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
	curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
	curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
	$output = curl_exec( $ch );
	curl_close( $ch );
	$result = json_decode( $output, true );
	return $result["query"]["tokens"]["csrftoken"];
}
// Step 4: POST request to send an email
function sendemail( $csrftoken ) {
	global $endPoint;
	$params4 = [
		"action" => "emailuser",
		"target" => "ABCD",
		"subject" => "API test",
		"text" => "Good to see you",
		"token" => $csrftoken,
		"format" => "json"
	];
	$ch = curl_init();
	curl_setopt( $ch, CURLOPT_URL, $endPoint );
	curl_setopt( $ch, CURLOPT_POST, true );
	curl_setopt( $ch, CURLOPT_POSTFIELDS, http_build_query( $params4 ) );
	curl_setopt( $ch, CURLOPT_RETURNTRANSFER, true );
	curl_setopt( $ch, CURLOPT_COOKIEJAR, "cookie.txt" );
	curl_setopt( $ch, CURLOPT_COOKIEFILE, "cookie.txt" );
	$output = curl_exec( $ch );
	curl_close( $ch );
	echo ( $output );
}

JavaScript

[edit ]
/* 
 send_email.js

 MediaWiki API Demos
 Demo of `Emailuser` module: sending POST request to send email to wiki user
 MIT license
*/
varrequest=require('request').defaults({jar:true}),
url="https://en.wikipedia.org/w/api.php";
// Step 1: GET request to fetch login token
functiongetLoginToken(){
varparams_0={
action:"query",
meta:"tokens",
type:"login",
format:"json"
};
request.get({url:url,qs:params_0},function(error,res,body){
if(error){
return;
}
vardata=JSON.parse(body);
loginRequest(data.query.tokens.logintoken);
});
}
// Step 2: POST request to log in. 
// Use of main account for login is not
// supported. Obtain credentials via Special:BotPasswords
// (https://www.mediawiki.org/wiki/Special:BotPasswords) for lgname & lgpassword
functionloginRequest(login_token){
varparams_1={
action:"login",
lgname:"bot_username",
lgpassword:"bot_password",
lgtoken:login_token,
format:"json"
};
request.post({url:url,form:params_1},function(error,res,body){
if(error){
return;
}
getCsrfToken();
});
}
// Step 3: GET request to fetch CSRF token
functiongetCsrfToken(){
varparams_2={
action:"query",
meta:"tokens",
format:"json"
};
request.get({url:url,qs:params_2},function(error,res,body){
if(error){
return;
}
vardata=JSON.parse(body);
send_email(data.query.tokens.csrftoken);
});
}
// Step 4: POST request to send an email
functionsend_email(csrf_token){
varparams_3={
action:"emailuser",
target:"ABCD",
subject:"API Test",
text:"Hello",
token:csrf_token,
format:"json"
};
request.post({url:url,form:params_3},function(error,res,body){
if(error){
return;
}
console.log(body);
});
}
// Start From Step 1
getLoginToken();

MediaWiki JS

[edit ]
/*
	send_email.js
	MediaWiki API Demos
	Demo of `Emailuser` module: sending POST request to send email to wiki user
	MIT License
*/
varparams={
action:'emailuser',
target:'ABC',
subject:'Hi',
text:'Just wanted to say hi',
format:'json'
},
api=newmw.Api();
api.postWithToken('csrf',params).done(function(data){
console.log(data);
});

Possible errors

[edit ]

In addition to the usual stuff :

Code Info
cantsend You are not logged in, you do not have a confirmed email address, or you are not allowed to send email to other users, so you cannot send email.
blockedfrommail You have been blocked from sending email.
usermaildisabled User email has been disabled
notarget ⧼apierror-notarget⧽
noemail This user has not specified a valid email address.
nowikiemail This user has chosen not to receive email from other users.

Checking emailable status

[edit ]

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: 

newmw.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;


The following documentation is the output of Special:ApiHelp/emailuser, automatically generated by the pre-release version of MediaWiki that is running on this site (MediaWiki.org).

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.

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]


AltStyle によって変換されたページ (->オリジナル) /