API

..............................................................................................................................................................................................................................................................................................

General information

The API functions using the HTTP protocol.

Request format: standard HTTP GET or POST, application/x-www-form-urlencoded

Response format: JSON.

Server-to-Server requests

The Server-to-Server API verifies the client’s authorization and API address.

The login and secret are passed using Basic HTTP Authorization in the Authorization header

Authorization: Basic base64('login:secret')

The login and secret, and the list of allowed IP addresses, can be changed in the project settings

Endpoint - https://mailer.mail.ru/

Both API versions are current and equivalent, with v2 mostly duplicating the interface's capabilities

swagger is available for api/v2

ping https://mailer.mail.ru/api/watchman/ping/

Sending a single email

POST /api/mailer/send/

Sends an email to the specified address. Cannot be used for bulk mailings!

Parameter	Type	Description
email	email	The user's email address
uid	str	The user’s UID. Required for MY.GAMES projects
letter	int	Email template ID
retry	int	Retry sending in case of SMTP server unavailability. 1 by default
send_id	string	Any unique value within the project. Emails with the same send_id will not be resent. The send_id is stored in the mailer for at least one day. Optional
language	string	Email template language Optional
resolve.xxx	string	Additional parameters for profile filtering. See below for available parameters
pin.xxx	string	Additional parameters for the template. pin.xxx will be available in the template as {{ xxx }}. DO NOT pin index fields pin.uid, pin.email, pin.phone, pin.wp_token. Use any other fields such as pin.promo_email instead
header.xxx	string	Additional email header parameters. The only headers allowed currently are 'Reply-To', 'Cc', and 'Bcc'. To add new ones, please contact Andrei Moiseev.
attach.xxx	url	The attachment file that can be used in the template. Such as: <img src="cid:xxx">. The file will be downloaded from the specified URL and will have xxx as its content ID. The content-type is taken from the server response header. If the attachment is a text file containing non-ASCII letters, it should be encoded in utf-8, as in content_type='message/rfc822; charset=utf-8'. The timeout for a single request is 1 second. The file will be requested at the time of the API call. Currently the cumulative limit for attachments is 4.
attachment.xxx	url	Attachment file. The file will be downloaded from the specified URL and will have xxx as its name. The content-type is taken from the server response header. If the attachment is a text file containing non-ASCII letters, it should be encoded in utf-8, as in content_type='message/rfc822; charset=utf-8'. The timeout for a single request is 1 second. The file will be requested at the time of the API call. Currently the cumulative limit for attachments is 4.

Successful dispatch

{

"sent": 1,

"retry": 0,

"status": "ok"

}

Email added to the queue

{

"sent": 0,

"retry": 1,

"status": "ok"

}

Template language not found

{

"args_errors": {

"language": [

"Bad language. Received: 'en'. Available: ['ru']"

]

"status": "fail",

"code": 3000,

"msg": "incorrect arguments"

}

An email with the same send_id is already being sent

{

"status": "fail",

"msg": "send in progress",

"code": 3017,

"current_status": "W"

}

An email with the same send_id has already been sent

{

"status": "fail",

"msg": "already sent",

"code": 3016,

"sent_at": "1548920365"

}

Flags and parameters for resolve.xxx

not_check_spam_quarantine - Bool. Spam quarantine check disabled, default=True
send_to_corp - send to @corp.mail.ru, default= True
not_check_subscription - Bool. Do not check subscribers / unsubscribers. This email will be sent to any user regardless of their subscription status. default=True
not_check_sent_quarantine - Bool. Ignore sending policy ("No more than N messages in M days per user"). For example, "No more than 2 messages in 15 days per user". N and M are specified in the project settings, default = True
min_send_interval - Integer. Do not send the user an email with the same ID within N seconds, default=0

Counters in the Stats field

viewed - total emails viewed
selected - selected for sending
stop_noaddress - the profile does not have an email (may happen if uid is passed instead of email)
stop_gdpr - user removed due to GDPR
stop_unsubscr - user unsubscribed (not checked by default for mailing campaign API)
stop_nonexistent - hard bounce encountered
stop_inactive - SWA considers the user disabled or non-existent
stop_sendlog_added - the profile has been quarantined due to failure to comply with the project's sending policy

curl example

curl --request POST 'https://mailer.mail.ru/api/mailer/send/' \

--header 'Content-Type: application/x-www-form-urlencoded' \

--header 'Authorization: Basic ***' \

--data-urlencode 'email=user@mail.ru' \

--data-urlencode 'letter=1234' \

--data-urlencode 'pin.xxx=value'

..............................................................................................................................................................................................................................................................................................

Sending a single SMS

POST /api/sms/send/

Parameter	Type	Description
phone	phone	Phone number
message	int	SMS message ID for sending
pin.xxx	string	Additional parameters for the template. pin.xxx will be available in the template as {{ xxx }}

Successful dispatch

{

"sent": 1,

"status": "ok",

}

Dispatch failed

{

"sent": 0,

"status": "fail",

}

Working with profiles

Users can be identified using one of three fields: * uid - User ID within the project * email - Their email address * phone - Their phone number, if present

At least one of these parameters must be included in profile-related calls.

User creation / update

POST /api/profiles/update/

Creates a new user or updates an existing one based on the provided fields.

Parameters beginning with pin should be used for passing all non-index fields.

All fields must be declared in advance via project settings in the web interface. All undeclared fields will be ignored.

Updating profile fields may trigger automated mailings.

Parameter	Type	Description
uid	string	uid - user ID in the project․ Optional
phone	phone	User phone number. Optional
email	email	User email. Optional
pin.xxx		Project-specific custom profile fields
unpin.xxx		Clears selected profile fields. The value provided with this field will be ignored.

Successful update

{

"status": "ok"

}

System fields of the user profile

Internal name	Name	Data type	API-based update capability
subscribed_at	Subscription date (single opt-in)	Date and time	No
confirmed_at	Email confirmation date (double opt-in)	Date and time	No
unsubscribed_at	Subscription cancellation date	Date and time	No
subscribed_categories	Subscription categories	JSON	No
spam_reported_at	Date added to spam quarantine	Date and time	No
bounce_error	Last bounce error	String	No
bounce_at	Date of the last bounce error	Date and time	No
blacklisted_at	Date added to the blacklist	Date and time	No
lang	The user’s language	String	Yes
gender	Gender	String	Yes
birthday	Birth date	Date and time	Yes
email_verified	Email confirmed	Flag	Yes
gcnotif_unsubscribe_at	Notification unsubscribe date	Date and time	No
uid	The user’s ID	String	Yes
email	Email	String	Yes
phone	Phone number	String	Yes
wp_token	WebPush token	String	Yes

Retrieving a profile

GET /api/profiles/get/

Parameter	Type	Description
uid	string	uid - user ID in the project․ Optional
phone	phone	User phone number. Optional
email	email	User email. Optional

Profile found

{

"status": "ok",

"profile": {

"uid": 24234,

"email": "user@mail.ru",

"level": 33,

"something_else": "data"

}

Retrieving all profiles by email For MY.GAMES projects

GET /api/profiles/get_all/

Parameter	Type	Description
email	email	User email.

Profile found

{

"status": "ok",

"profiles": [{

"uid": 24234,

"email": "user@mail.ru",

"level": 33,

"something_else": "data"

{

"uid": 264563,

"email": "user@mail.ru",

"level": 3,

"something_else": "other_data"

}]

}

Profile verification

POST /api/profiles/verify/

Marks a user as verified

It is preferable to use the micro format (https://mailer.mail.ru/docs/view/templates/).

Parameter	Type	Description
uid	string	uid - user ID in the project․ Optional
phone	phone	User phone number. Optional
email	email	User email. Optional

Marketing email subscription confirmation

POST /api/profiles/confirm/

Flags the user as opted-in to receive marketing newsletters. It is preferable to use the micro format (https://mailer.mail.ru/docs/view/templates/).

Parameter	Type	Description
uid	string	uid - user ID in the project․ Optional
phone	phone	User phone number. Optional
email	email	User email. Optional
not_subscribe	bool	Not to subscribe if subscription is absent
ip	ip	The user's IP address for GDPR logging in Server-to-Server requests. Optional
agent	string	The user's User-Agent for GDPR logging in Server-to-Server requests. Optional

Profile subscription

POST /api/profiles/subscribe/

POST /api/profiles/subscribe/{{token}}/- using secure link

Flags the user as subscribed to all project categories. The list of categories can be modified via the project settings in the Mailer web interface. The project MUST NOT subscribe the user to mailings without their explicit consent. EULAs and other legal documents do not count as explicit consent. The project MUST NOT subscribe the user to all categories if they have only subscribed to some. The project bears responsibility for such mailings.

Parameter	Type	Description
uid	string	uid - user ID in the project․ Optional
phone	phone	User phone number. Optional
email	email	User email. Optional
lang	string	The language to be set in the profile. Format: ru,en,fr or en_US,ru_RU,fr_FR. Optional
ip	ip	The user's IP address for GDPR logging in Server-to-Server requests. Optional
agent	string	The user's User-Agent for GDPR logging in Server-to-Server requests. Optional

The profile is subscribed

{

"status": "ok",

"profile_categories": [1, 2, 3, 4, 5],

}

Profile subscription to a single category

POST /api/profiles/subscribe_category/

Adds only the specified category to the subscriptions

Parameter	Type	Description
uid	string	uid - user ID in the project․ Optional
phone	phone	User phone number. Optional
email	email	User email. Optional
category	int	Subscribing category number
ip	ip	The user's IP address for GDPR logging in Server-to-Server requests. Optional
agent	string	The user's User-Agent for GDPR logging in Server-to-Server requests. Optional

Returns the list of all subscribed categories

{

"status": "ok"

"profile_categories": [1, 2, 5],

}

Profile unsubscription

POST /api/profiles/unsubscribe/

Marks the user as unsubscribed from all project categories. Unsubscribed users will not receive emails from the project (unless explicitly overridden).

Parameter	Type	Description
uid	string	uid - user ID in the project․ Optional
phone	phone	User phone number. Optional
email	email	User email. Optional
ip	ip	The user's IP address for GDPR logging in Server-to-Server requests. Optional
agent	string	The user's User-Agent for GDPR logging in Server-to-Server requests. Optional

User unsubscribed

{

"status": "ok"

"profile_categories": [],

}

Profile unsubscribing from a single category

POST /api/profiles/unsubscribe_category/

Removes only the specified category from the subscriptions

Parameter	Type	Description
uid	string	uid - user ID in the project․ Optional
phone	phone	User phone number. Optional
email	email	User email. Optional
category	int	Unsubscribing category number
ip	ip	The user's IP address for GDPR logging in Server-to-Server requests. Optional
agent	string	The user's User-Agent for GDPR logging in Server-to-Server requests. Optional

Returns the list of all subscribed categories

{

"status": "ok"

"profile_categories": [1, 2],

}

Profile unsubscribing using a secure link

POST /api/profiles/unsubscribe/{{token}}/

Marks the user as unsubscribed from all project categories. Unsubscribed users will not receive emails from the project (unless explicitly overridden).

Parameter	Type	Description
uid	string	uid - user ID in the project․ Optional
phone	phone	User phone number. Optional
email	email	User email. Optional
ip	ip	The user's IP address for GDPR logging in Server-to-Server requests. Optional
agent	string	The user's User-Agent for GDPR logging in Server-to-Server requests. Optional

User unsubscribed

{

"status": "ok"

"profile_categories": [],

}

Changing user categories

POST /api/profiles/set_subscriptions/

Sets a new list of categories the user is subscribed to. If the list of categories is empty, it works the same as unsubscribing the user.

Parameter	Type	Description
uid	string	uid - user ID in the project․ Optional
phone	phone	User phone number. Optional
email	email	User email. Optional
categories	[]int	The list of category IDs to which the user is subscribed
ip	ip	The user's IP address for GDPR logging in Server-to-Server requests. Optional
agent	string	The user's User-Agent for GDPR logging in Server-to-Server requests. Optional

Example: categories=1&categories=4&categories=6

Settings have been changed

{

"status": "ok",

"profile_categories": [1, 4, 6],

}

Changing user profile categories using a secure link

POST /api/profiles/set_link_subscriptions/{{token}}/

Sets a new list of categories the user is subscribed to. If the list of categories is empty, it works the same as unsubscribing the user.

Parameter	Type	Description
profile_categories	[]int	The list of category IDs to which the user is subscribed
ip	ip	The user's IP address for GDPR logging in Server-to-Server requests. Optional
agent	string	The user's User-Agent for GDPR logging in Server-to-Server requests. Optional

Example: profile_categories=1&profile_categories=4&profile_categories=6

Settings have been changed

{

"status": "ok",

"profile_categories": [1, 4, 6],

}

Retrieving user categories

GET /api/profiles/get_subscriptions/

Returns a list of categories user is subscribed to. Also returns information about all possible project categories.

Parameter	Type	Description
uid	string	uid - user ID in the project․ Optional
phone	phone	User phone number. Optional
email	email	User email. Optional
lang	string	Desired localization of category names. Optional For example: de_DE

Retrieving user categories using a secure link

GET /api/profiles/get_link_subscriptions/{{token}}/

Returns a list of categories user is subscribed to. Also returns information about all possible project categories.

User settings

{

"status": "ok",

"profile_categories": [1, 3],

"project": {

"name": "The Project",

"logo": "https://mailer.mail.ru/path/to/logo.png",

"categories": [

{

"id": 1,

"title": "Security Notifications",

"description": "Important messages about your account",

{

"id": 2,

"title": "News and promos",

"description": "Information about new products",

{

"id": 3,

"title": "Messages from other users",

"description": "Notifications about personal messages from other users",

]

}

POST /api/profiles/void/

Deletes the user from the mailer and adds them to the GDPR quarantine. The user can no longer be added to the mailer.

Parameter	Type	Description
uid	string	uid - user ID in the project․ Optional
phone	phone	User phone number. Optional
email	email	User email. Optional

If the project has the is_internal flag set, an additional parameter ext_ids can be passed to remove a user from multiple projects at once.

Parameter	Type	Description
ext_ids	[]str	Project’s external id Optional

Example: email=test@mail.ru&ext_ids=project1.my.com&ext_ids=project2.my.com

{

"status": "ok"

}

User deletion

POST /api/profiles/delete/

Do not delete users unless ABSOLUTELY necessary!

Removes a user from the mailer. Deletes all history and quarantines.

Parameter	Type	Description
uid	string	uid - user ID in the project․ Optional
phone	phone	User phone number. Optional
email	email	User email. Optional

Example: email=test@mail.ru

User deleted

{

"status": "ok"

}

User not found

{

"status": "fail",

"code": 3008,

"msg": "no such profile"

}

Sending double-opt-in emails based on sezam_id

GET /api/mailer/send_verify/

Parameter	Type	Description
email	email	User email
ext_id	int/str	Project ID

Successful dispatch

{

"status": "ok",

"letter_id": 1234

}

Error codes

Error code	Description
3000	Incorrect parameters
3001	Access denied: no Authorization header
3001	Access denied: incorrect login or secret
3001	Access denied: IP not in the allowed list
3002	Email, SMS, or GC notification not found.
3003	Too many addresses
3004	Project not found
3005	The object is inaccessible
3006	Failed to send message
3007	Incorrect profile fields, such as a wrong date for date fields
3008	Profile not found
3013	Unsupported API method
3014	The call frequency for this operation has been exceeded
3015	The message was not sent: the user did not pass the filters
3016	The message was not sent: a message with the same send_id was already dispatched
3017	The message was not sent: a message with the same send_id is being dispatched
3018	Incorrect JWT token
3019	The template for the email/notification/SMS/push is archived
3020	The project's sending policy does not support this method

API

Contents

General information

Both API versions are current and equivalent, with v2 mostly duplicating the interface's capabilities

Sending a single email

Successful dispatch

Email added to the queue

Template language not found

An email with the same send_id is already being sent

An email with the same send_id has already been sent

Flags and parameters for resolve.xxx

Counters in the Stats field

curl example

Sending a single SMS

Successful dispatch

Dispatch failed

Working with profiles

User creation / update

Successful update

System fields of the user profile

Retrieving a profile

Profile found

Retrieving all profiles by email For MY.GAMES projects

Profile found

Profile verification

Marketing email subscription confirmation

Profile subscription

The profile is subscribed

Profile subscription to a single category

Returns the list of all subscribed categories

Profile unsubscription

User unsubscribed

Profile unsubscribing from a single category

Returns the list of all subscribed categories

Profile unsubscribing using a secure link

User unsubscribed

Changing user categories

Settings have been changed

Changing user profile categories using a secure link

Settings have been changed

Retrieving user categories

Retrieving user categories using a secure link

User settings

User deletion and inclusion in GDPR quarantine

The user has been deleted and added to the GDPR quarantine

User deletion

User deleted

User not found

Sending double-opt-in emails based on sezam_id

Successful dispatch

Error codes