Notifications.sendEmail

From Facebook Developer Wiki

Jump to: navigation, search

Contents

Description

Sends an email to the specified users, who have both authorized your application and granted it the email extended permission. For users who granted your application the email permission prior to the introduction of the new profile in September, 2008, you have a limit as to how many email messages you may send to them per day (check for the limit through admin.getAllocation; see the note below for more details). You can send an email message to up to 100 users each time you call this method.

Email messages sent by way of this call come from the facebookappmail.com domain; previously, they came from the facebookmail.com domain.

Notification emails are sent with the Content-Transfer-Encoding as quoted-printable as opposed to 8-bit. This is done to prevent the unusual behavior of the PHP mailer when an email has lines longer than 998 characters, per the SMTP RFC. Email messages are wrapped with soft breaks, per the quoted-printable encoding.

This method requires a session key for desktop applications, which may send email only to the person whose session it is. This method does not require a session for Web applications.

For a list of allowed and disallowed HTML and FBML tags, see Allowed FBML and HTML Tags.

Parameters

RequiredNameTypeDescription
required api_key string The application key associated with the calling application.
sig string An MD5 hash of the current request and your secret key, as described in the How Facebook Authenticates Your Application.
v string This must be set to 1.0 to use this version of the API.
recipients array A comma-separated list of recipient IDs. The recipients must be people who have already added your application. You can email up to 100 people at a time.
subject string The subject of the email message. As of 10/28/2008, the subject will accept a limited set of FBML tags, including names, and tags related to internationalization.
text string The plain text version of the email content. You must include a non-empty value for at least one of either the fbml or text parameters. The FBML input takes precedence, but if the given FBML value is invalid or cannot be rendered, then the text will be used instead. There is currently no character limit on the length of either the text or FBML body.
fbml string The FBML version of the email. You must include a non-empty value for at least one of either the fbml or text parameters. The fbml parameter is a stripped-down set of FBML that allows only HTML/FBML tags that result in text, links, linebreaks, as well as tags related to internationalization.
optional session_key string The session key of the user for whom you are creating the listing.
Note: A session key is always required for desktop applications. It is never required for Web applications.
format string The desired response format, which can be either XML or JSON. (Default value is XML.)
callback string Name of a function to call. This is primarily to enable cross-domain JavaScript requests using the <script> tag, also known as JSONP, and works with both the XML and JSON formats. The function will be called with the response passed as the parameter.

Example Requests

$result=$facebook->api_client->notifications_sendEmail($csv,"Test: this should appear in the subject", "This should appear in the body (plain text)", "Test: <b><i><u>this should appear in the body</u></i></b> (HTML)"); echo "sent to $result targets of ". count(str_getcsv("$csv",",")) . "total.";

Response

Returns a comma-separated list of the recipients to whom the email was successfully sent.

Example Return XML

<?xml version="1.0" encoding="UTF-8"?> <notifications_sendEmail_response xmlns="http://api.facebook.com/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://api.facebook.com/1.0/ http://api.facebook.com/1.0/facebook.xsd">211031,1160</notifications_sendEmail_response>

Error Codes

CodeDescription
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 used.
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.
200 Insufficient permissions.

Notes

  • This method does not require a session_key, unless it is being called by a desktop application.
  • An alternate way to send email (subject to the same restrictions here) is to query for a user's proxied_email address. For more information, see Proxied Email.
  • If a user replies to an application email, the response does not get sent to the application. You can include information in your email template that provides guidance on how the user can contact you or your application (such as by going to your application About Page/application profile).
  • On November 19th, 2008, several changes to email policy were announced, including an expanded set of allowed HTML and FBML tags, and the removal of the limit on emails sent per day in the case that the user authorized the application on the new profile and then explicitly granted permission for sending email. If the user added the application on the old profile, then they are still subject to the allocation limits. If you wish to remove this allocation limit, you must have the user re-grant the email extended permission by first calling auth.revokeExtendedPermission, and then using one of the normal methods to prompt the user to grant it again.
  • Bug: You can use inline styles on HTML elements (e.g., <div style="color: red">) but there seems to be a bug when trying to use style tags (e.g., <style> #mydiv { color: red } </style>). For more information, see http://bugs.developers.facebook.com/show_bug.cgi?id=4055.
reference