Notifications.sendEmail
From Facebook Developer Wiki
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
| Required | Name | Type | Description | |
| 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
Response
Returns a comma-separated list of the recipients to whom the email was successfully sent.
Example Return XML
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 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_emailaddress. 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.
