Sending messages and notifications

The Mail.Ru platform allows emails and notifications to be sent to a user of a partner game. The emails are sent to the user’s Mail.Ru email address used to log into the game. Notifications are displayed on the http://games.mail.ru/ site and on the user’s desktop if they have Game Center installed.

Sending messages

  1. API response format - json.
  2. Protocol for transferring data - https.
  3. Requests must take place only between the servers of the partner and Mail.Ru.

Request format:

# Sending a notification
POST https://games.mail.ru/app/[GMRID]/send/notification

# Sending an email
POST https://games.mail.ru/app/[GMRID]/send/email

Main POST parameters:

  • <uid> - user’s id (sent to partner upon registration)
  • <template> - template of messages, more information in the "Message templates" section
  • <template_param> - a json object with parameters that will be placed in the template (optional parameter)
  • <sign> - a unique digital signature

Signature calculation

To formulate a request signature (the sign parameter) you must:

1. Take all the POST parameters that will be sent in the request (with the exception of sign, since it is not yet calculated):

  • <uid> - 596343600
  • <template> - greetings
  • <template_param> - {}

2. Sort the parameters by key

{
    "template": "greetings",
    "template_param": "{}",
    "uid": "596343600"
}

3. Insert the key value into the line

$str = "template=greetingstemplate_param={}uid=596343600"

4. Generate a signature

$sign = md5($str . $secret)

$secret - game’s unique code. The partner can find this in the developer dashboard, on the game’s page, under the "System properties" tab. The relevant field is titled "Secret for api.games.mail.ru".

5. Add the sign parameter to the request.

Response format:

Successful:

{
    "status": "ok"
}

Errors:

# User not found
{"status": "error", "errcode': 1003, "errmsg": "user not found"}

# Incorrect user signature
{"status": "error", "errcode': 5001, "errmsg": "invalid sign"}

# Exceeded message send limit
{"status": "error", "errcode': 7001, "errmsg": "send limit exceeded"}

# Incorrect template for sending
{"status": "error", "errcode': 7002, "errmsg": "invalid template"}

# Incorrect template parameter
{"status": "error", "errcode': 7003, "errmsg": "invalid template param"}

# Error sending message
{"status": "error", "errcode': 7004, "errmsg": "can't send to user"}

# User does not have an email address to which an email can be sent (social network authorization)
{"status": "error", "errcode': 7005, "errmsg": "user has no email"}
  • "errcode" - internal error code
  • "errmsg" - error code description

Message limitations:

  1. The number of emails sent by a partner per day is limited by the DAU for the previous day.
  2. The number of notifications sent by a partner per day is limited by the DAU for the previous day.
  3. Messages cannot contain arbitrary text. Messages are based on premade templates in which you can insert parameters. More details can be found in the "Message templates" section.

Message templates

1. Greetings

Thanks for registering
We’re very glad you’ve registered for the game {{game_name}}
  • Template value - greetings
  • Required parameters in template_param - none
  • Optional parameters in template_param - none
  • Automatic parameters - game_name