MediaPost Social Network

 
Content
API
UPML
UPML Console

Up.notifications.send

Send a notification to a set of users. You can send emails to users that have added the application without any confirmation, or you can direct a user of your application to the URL returned by this function to email users who have not yet added your application. You can also send messages to the users' notification page without needing any confirmation.

Parameters

Type Name Required Description
string api_key ✔ The application key associated with the calling application.
string session_key ✔ The session key of the logged in user.
string community ✔ Community system name. Use up.community.getList method to retrieve available communities.
string sig ✔ An MD5 hash of the current request and your secret key, as described in the authentication guide.
string format Desired response format. Either XML (default) or JSON.
array to_ids ✔ Comma-separated list of recipient ids. These must be either friends of the logged-in user or people who have added your application. To send a notification to the current logged in user without a name prepended to the message, set to_ids to the empty string.
string content ✔ Notification content

Example return XML

<?xml version="1.0" encoding="UTF-8"?>
<notifications_send_response>1</notifications_send_response>

Error codes

Code Description
1 An unknown error occurred. Please resubmit the request.
2 The service is not available at this time.
4 The application has reached the maximum number of requests allowed. More requests are allowed once the time window has completed.
5 The request came from a remote address not allowed by this application.
100 Invalid parameter
101 The api key submitted is not associated with any known application.
102 The session key was improperly submitted or has reached its timeout. Direct the user to log in again to obtain another key.
103 The submitted call_id was not greater than the previous call_id for this session.
104 Incorrect signature.

Gotchas

  • It seems as if an email won't get sent if the text of the email begins with an up:name tag. I would assume this is due to the fact that the sender's name is auto appended.
  • If you are using an older version of up_php5_restlib.php or up_php4_restlib.php ( line 258 )

Then change this line (256) in notifications_send from - 

256: array('to_ids' => $to_ids, 'markup' => $markup, 'no_email' => $no_email));

To - 

256: array('to_ids' => $to_ids, 'notification' => $markup, 'email' => $no_email));

This is needed otherwise the script will always return Invalid Paramater, with this change the send will work.

  • The user name of the logged-in user will be prepended to the notification. Your 'notification' and 'email' UPML should take this into account by starting with a verb. This does not happen if you set to_ids to be empty.
  • As far as I can tell, there is no way to tell when notifications fail due to to user not being a friend. Using the PHP API, null is returned either way.
  • When the e-mail limit is hit, the user isn't presenting with the confirmation page anymore, and is automatically redirected to the &next= url.
  • The confirmation page shows only ONE e-mail, with the first friend's e-mail address. This may (incorrectly) cause you to think the e-mail will only send to that one friend. However, when the user clicks "send e-mail" the e-mail gets sent to ALL the users in the ID list.

Allowed Code

For line breaks use
as the mail is intended for HTML email clients only. See example email source below: 

--b1_df52415e91cd869f3947877c5dd0587a
Content-Type: text/plain; charset = "UTF-8"
Content-Transfer-Encoding: 8bit

This message contains a rich-text HTML portion. Consult your mail client's documentation
for infomation on how to view it.

--b1_df52415e91cd869f3947877c5dd0587a
Content-Type: text/html; charset = "UTF-8"
Content-Transfer-Encoding: 8bit

Fred Bloggs says Hi!

--b1_df52415e91cd869f3947877c5dd0587a--

See also