Subversion-Projekte lars-tiefland.php_share

Revision

Details | Letzte Änderung | Log anzeigen | RSS feed

Revision Autor Zeilennr. Zeile
1 lars 1 
<?php
2 
/*
3 
 * Copyright 2010-2012 Amazon.com, Inc. or its affiliates. All Rights Reserved.
4 
 *
5 
 * Licensed under the Apache License, Version 2.0 (the "License").
6 
 * You may not use this file except in compliance with the License.
7 
 * A copy of the License is located at
8 
 *
9 
 *  http://aws.amazon.com/apache2.0
10 
 *
11 
 * or in the "license" file accompanying this file. This file is distributed
12 
 * on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
13 
 * express or implied. See the License for the specific language governing
14 
 * permissions and limitations under the License.
15 
 */
16 
 
17 
/**
18 
 * This is the API Reference for Amazon Simple Email Service (Amazon SES). This documentation is
19 
 * intended to be used in conjunction with the Amazon SES Getting Started Guide and the Amazon SES
20 
 * Developer Guide.
21 
 *
22 
 * For specific details on how to construct a service request, please consult the <a href=
23 
 * "http://docs.amazonwebservices.com/ses/latest/DeveloperGuide">Amazon SES Developer Guide</a>.
24 
 *
25 
 * <p class="note">
26 
 * The endpoint for AWS Email Service is located at:
27 
 * <em>https://email.us-east-1.amazonaws.com</em>
28 
 * </p>
29 
 *
30 
 * @version 2012.01.16
31 
 * @license See the included NOTICE.md file for complete information.
32 
 * @copyright See the included NOTICE.md file for complete information.
33 
 * @link http://aws.amazon.com/ses/ Amazon Simple Email Service
34 
 * @link http://aws.amazon.com/ses/documentation/ Amazon Simple Email Service documentation
35 
 */
36 
class AmazonSES extends CFRuntime
37 
{
38 
	/*%******************************************************************************************%*/
39 
	// CLASS CONSTANTS
40 
 
41 
	/**
42 
	 * Specify the queue URL for the United States East (Northern Virginia) Region.
43 
	 */
44 
	const REGION_US_E1 = 'email.us-east-1.amazonaws.com';
45 
 
46 
	/**
47 
	 * Specify the queue URL for the United States East (Northern Virginia) Region.
48 
	 */
49 
	const REGION_VIRGINIA = self::REGION_US_E1;
50 
 
51 
	/**
52 
	 * Default service endpoint.
53 
	 */
54 
	const DEFAULT_URL = self::REGION_US_E1;
55 
 
56 
 
57 
	/*%******************************************************************************************%*/
58 
	// CONSTRUCTOR
59 
 
60 
	/**
61 
	 * Constructs a new instance of <AmazonSES>.
62 
	 *
63 
	 * @param array $options (Optional) An associative array of parameters that can have the following keys: <ul>
64 
	 * 	<li><code>certificate_authority</code> - <code>boolean</code> - Optional - Determines which Cerificate Authority file to use. A value of boolean <code>false</code> will use the Certificate Authority file available on the system. A value of boolean <code>true</code> will use the Certificate Authority provided by the SDK. Passing a file system path to a Certificate Authority file (chmodded to <code>0755</code>) will use that. Leave this set to <code>false</code> if you're not sure.</li>
65 
	 * 	<li><code>credentials</code> - <code>string</code> - Optional - The name of the credential set to use for authentication.</li>
66 
	 * 	<li><code>default_cache_config</code> - <code>string</code> - Optional - This option allows a preferred storage type to be configured for long-term caching. This can be changed later using the <set_cache_config()> method. Valid values are: <code>apc</code>, <code>xcache</code>, or a file system path such as <code>./cache</code> or <code>/tmp/cache/</code>.</li>
67 
	 * 	<li><code>key</code> - <code>string</code> - Optional - Your AWS key, or a session key. If blank, the default credential set will be used.</li>
68 
	 * 	<li><code>secret</code> - <code>string</code> - Optional - Your AWS secret key, or a session secret key. If blank, the default credential set will be used.</li>
69 
	 * 	<li><code>token</code> - <code>string</code> - Optional - An AWS session token.</li></ul>
70 
	 * @return void
71 
	 */
72 
	public function __construct(array $options = array())
73 
	{
74 
		$this->api_version = '2010-12-01';
75 
		$this->hostname = self::DEFAULT_URL;
76 
		$this->auth_class = 'AuthV3Query';
77 
 
78 
		return parent::__construct($options);
79 
	}
80 
 
81 
 
82 
	/*%******************************************************************************************%*/
83 
	// SETTERS
84 
 
85 
	/**
86 
	 * This allows you to explicitly sets the region for the service to use.
87 
	 *
88 
	 * @param string $region (Required) The region to explicitly set. Available options are <REGION_US_E1>.
89 
	 * @return $this A reference to the current instance.
90 
	 */
91 
	public function set_region($region)
92 
	{
93 
		// @codeCoverageIgnoreStart
94 
		$this->set_hostname($region);
95 
		return $this;
96 
		// @codeCoverageIgnoreEnd
97 
	}
98 
 
99 
 
100 
	/*%******************************************************************************************%*/
101 
	// CONVENIENCE METHODS
102 
 
103 
	/**
104 
	 * Throws an error because SSL is required for the Amazon Email Service.
105 
	 *
106 
	 * @return void
107 
	 */
108 
	public function disable_ssl()
109 
	{
110 
		throw new Email_Exception('SSL/HTTPS is REQUIRED for Amazon Email Service and cannot be disabled.');
111 
	}
112 
 
113 
 
114 
	/*%******************************************************************************************%*/
115 
	// SERVICE METHODS
116 
 
117 
	/**
118 
	 * Deletes the specified email address from the list of verified addresses.
119 
	 *
120 
	 * @param string $email_address (Required) An email address to be removed from the list of verified addreses.
121 
	 * @param array $opt (Optional) An associative array of parameters that can have the following keys: <ul>
122 
	 * 	<li><code>curlopts</code> - <code>array</code> - Optional - A set of values to pass directly into <code>curl_setopt()</code>, where the key is a pre-defined <code>CURLOPT_*</code> constant.</li>
123 
	 * 	<li><code>returnCurlHandle</code> - <code>boolean</code> - Optional - A private toggle specifying that the cURL handle be returned rather than actually completing the request. This toggle is useful for manually managed batch requests.</li></ul>
124 
	 * @return CFResponse A <CFResponse> object containing a parsed HTTP response.
125 
	 */
126 
	public function delete_verified_email_address($email_address, $opt = null)
127 
	{
128 
		if (!$opt) $opt = array();
129 
		$opt['EmailAddress'] = $email_address;
130 
 
131 
		return $this->authenticate('DeleteVerifiedEmailAddress', $opt);
132 
	}
133 
 
134 
	/**
135 
	 * Returns the user's current sending limits.
136 
	 *
137 
	 * @param array $opt (Optional) An associative array of parameters that can have the following keys: <ul>
138 
	 * 	<li><code>curlopts</code> - <code>array</code> - Optional - A set of values to pass directly into <code>curl_setopt()</code>, where the key is a pre-defined <code>CURLOPT_*</code> constant.</li>
139 
	 * 	<li><code>returnCurlHandle</code> - <code>boolean</code> - Optional - A private toggle specifying that the cURL handle be returned rather than actually completing the request. This toggle is useful for manually managed batch requests.</li></ul>
140 
	 * @return CFResponse A <CFResponse> object containing a parsed HTTP response.
141 
	 */
142 
	public function get_send_quota($opt = null)
143 
	{
144 
		if (!$opt) $opt = array();
145 
 
146 
		return $this->authenticate('GetSendQuota', $opt);
147 
	}
148 
 
149 
	/**
150 
	 * Returns the user's sending statistics. The result is a list of data points, representing the
151 
	 * last two weeks of sending activity.
152 
	 *
153 
	 * Each data point in the list contains statistics for a 15-minute interval.
154 
	 *
155 
	 * @param array $opt (Optional) An associative array of parameters that can have the following keys: <ul>
156 
	 * 	<li><code>curlopts</code> - <code>array</code> - Optional - A set of values to pass directly into <code>curl_setopt()</code>, where the key is a pre-defined <code>CURLOPT_*</code> constant.</li>
157 
	 * 	<li><code>returnCurlHandle</code> - <code>boolean</code> - Optional - A private toggle specifying that the cURL handle be returned rather than actually completing the request. This toggle is useful for manually managed batch requests.</li></ul>
158 
	 * @return CFResponse A <CFResponse> object containing a parsed HTTP response.
159 
	 */
160 
	public function get_send_statistics($opt = null)
161 
	{
162 
		if (!$opt) $opt = array();
163 
 
164 
		return $this->authenticate('GetSendStatistics', $opt);
165 
	}
166 
 
167 
	/**
168 
	 * Returns a list containing all of the email addresses that have been verified.
169 
	 *
170 
	 * @param array $opt (Optional) An associative array of parameters that can have the following keys: <ul>
171 
	 * 	<li><code>curlopts</code> - <code>array</code> - Optional - A set of values to pass directly into <code>curl_setopt()</code>, where the key is a pre-defined <code>CURLOPT_*</code> constant.</li>
172 
	 * 	<li><code>returnCurlHandle</code> - <code>boolean</code> - Optional - A private toggle specifying that the cURL handle be returned rather than actually completing the request. This toggle is useful for manually managed batch requests.</li></ul>
173 
	 * @return CFResponse A <CFResponse> object containing a parsed HTTP response.
174 
	 */
175 
	public function list_verified_email_addresses($opt = null)
176 
	{
177 
		if (!$opt) $opt = array();
178 
 
179 
		return $this->authenticate('ListVerifiedEmailAddresses', $opt);
180 
	}
181 
 
182 
	/**
183 
	 * Composes an email message based on input data, and then immediately queues the message for
184 
	 * sending.
185 
	 *
186 
	 * <p class="important">
187 
	 * If you have not yet requested production access to Amazon SES, then you will only be able to
188 
	 * send email to and from verified email addresses. For more information, go to the <a href=
189 
	 * "http://docs.amazonwebservices.com/ses/latest/DeveloperGuide">Amazon SES Developer Guide</a>.
190 
	 * </p>
191 
	 * The total size of the message cannot exceed 10 MB.
192 
	 *
193 
	 * Amazon SES has a limit on the total number of recipients per message: The combined number of
194 
	 * To:, CC: and BCC: email addresses cannot exceed 50. If you need to send an email message to a
195 
	 * larger audience, you can divide your recipient list into groups of 50 or fewer, and then call
196 
	 * Amazon SES repeatedly to send the message to each group.
197 
	 *
198 
	 * For every message that you send, the total number of recipients (To:, CC: and BCC:) is counted
199 
	 * against your <em>sending quota</em> - the maximum number of emails you can send in a 24-hour
200 
	 * period. For information about your sending quota, go to the "Managing Your Sending Activity"
201 
	 * section of the <a href="http://docs.amazonwebservices.com/ses/latest/DeveloperGuide">Amazon SES
202 
	 * Developer Guide</a>.
203 
	 *
204 
	 * @param string $source (Required) The sender's email address.
205 
	 * @param array $destination (Required) The destination for this email, composed of To:, CC:, and BCC: fields. <ul>
206 
	 * 	<li><code>x</code> - <code>array</code> - Optional - This represents a simple array index. <ul>
207 
	 * 		<li><code>ToAddresses</code> - <code>string|array</code> - Optional - The To: field(s) of the message. Pass a string for a single value, or an indexed array for multiple values.</li>
208 
	 * 		<li><code>CcAddresses</code> - <code>string|array</code> - Optional - The CC: field(s) of the message. Pass a string for a single value, or an indexed array for multiple values.</li>
209 
	 * 		<li><code>BccAddresses</code> - <code>string|array</code> - Optional - The BCC: field(s) of the message. Pass a string for a single value, or an indexed array for multiple values.</li>
210 
	 * 	</ul></li>
211 
	 * </ul>
212 
	 * @param array $message (Required) The message to be sent. <ul>
213 
	 * 	<li><code>x</code> - <code>array</code> - Optional - This represents a simple array index. <ul>
214 
	 * 		<li><code>Subject</code> - <code>array</code> - Required - The subject of the message: A short summary of the content, which will appear in the recipient's inbox. <ul>
215 
	 * 			<li><code>x</code> - <code>array</code> - Optional - This represents a simple array index. <ul>
216 
	 * 				<li><code>Data</code> - <code>string</code> - Required - The textual data of the content.</li>
217 
	 * 				<li><code>Charset</code> - <code>string</code> - Optional - The character set of the content.</li>
218 
	 * 			</ul></li>
219 
	 * 		</ul></li>
220 
	 * 		<li><code>Body</code> - <code>array</code> - Required - The message body. <ul>
221 
	 * 			<li><code>x</code> - <code>array</code> - Optional - This represents a simple array index. <ul>
222 
	 * 				<li><code>Text</code> - <code>array</code> - Optional - The content of the message, in text format. Use this for text-based email clients, or clients on high-latency networks (such as mobile devices). <ul>
223 
	 * 					<li><code>x</code> - <code>array</code> - Optional - This represents a simple array index. <ul>
224 
	 * 						<li><code>Data</code> - <code>string</code> - Required - The textual data of the content.</li>
225 
	 * 						<li><code>Charset</code> - <code>string</code> - Optional - The character set of the content.</li>
226 
	 * 					</ul></li>
227 
	 * 				</ul></li>
228 
	 * 				<li><code>Html</code> - <code>array</code> - Optional - The content of the message, in HTML format. Use this for email clients that can process HTML. You can include clickable links, formatted text, and much more in an HTML message. <ul>
229 
	 * 					<li><code>x</code> - <code>array</code> - Optional - This represents a simple array index. <ul>
230 
	 * 						<li><code>Data</code> - <code>string</code> - Required - The textual data of the content.</li>
231 
	 * 						<li><code>Charset</code> - <code>string</code> - Optional - The character set of the content.</li>
232 
	 * 					</ul></li>
233 
	 * 				</ul></li>
234 
	 * 			</ul></li>
235 
	 * 		</ul></li>
236 
	 * 	</ul></li>
237 
	 * </ul>
238 
	 * @param array $opt (Optional) An associative array of parameters that can have the following keys: <ul>
239 
	 * 	<li><code>ReplyToAddresses</code> - <code>string|array</code> - Optional - The reply-to email address(es) for the message. If the recipient replies to the message, each reply-to address will receive the reply. Pass a string for a single value, or an indexed array for multiple values.</li>
240 
	 * 	<li><code>ReturnPath</code> - <code>string</code> - Optional - The email address to which bounce notifications are to be forwarded. If the message cannot be delivered to the recipient, then an error message will be returned from the recipient's ISP; this message will then be forwarded to the email address specified by the <code>ReturnPath</code> parameter.</li>
241 
	 * 	<li><code>curlopts</code> - <code>array</code> - Optional - A set of values to pass directly into <code>curl_setopt()</code>, where the key is a pre-defined <code>CURLOPT_*</code> constant.</li>
242 
	 * 	<li><code>returnCurlHandle</code> - <code>boolean</code> - Optional - A private toggle specifying that the cURL handle be returned rather than actually completing the request. This toggle is useful for manually managed batch requests.</li></ul>
243 
	 * @return CFResponse A <CFResponse> object containing a parsed HTTP response.
244 
	 */
245 
	public function send_email($source, $destination, $message, $opt = null)
246 
	{
247 
		if (!$opt) $opt = array();
248 
		$opt['Source'] = $source;
249 
 
250 
		// Required map (non-list)
251 
		$opt = array_merge($opt, CFComplexType::map(array(
252 
			'Destination' => (is_array($destination) ? $destination : array($destination))
253 
		), 'member'));
254 
 
255 
		// Required map (non-list)
256 
		$opt = array_merge($opt, CFComplexType::map(array(
257 
			'Message' => (is_array($message) ? $message : array($message))
258 
		), 'member'));
259 
 
260 
		// Optional list (non-map)
261 
		if (isset($opt['ReplyToAddresses']))
262 
		{
263 
			$opt = array_merge($opt, CFComplexType::map(array(
264 
				'ReplyToAddresses' => (is_array($opt['ReplyToAddresses']) ? $opt['ReplyToAddresses'] : array($opt['ReplyToAddresses']))
265 
			), 'member'));
266 
			unset($opt['ReplyToAddresses']);
267 
		}
268 
 
269 
		return $this->authenticate('SendEmail', $opt);
270 
	}
271 
 
272 
	/**
273 
	 * Sends an email message, with header and content specified by the client. The
274 
	 * <code>SendRawEmail</code> action is useful for sending multipart MIME emails. The raw text of
275 
	 * the message must comply with Internet email standards; otherwise, the message cannot be sent.
276 
	 *
277 
	 * <p class="important">
278 
	 * If you have not yet requested production access to Amazon SES, then you will only be able to
279 
	 * send email to and from verified email addresses. For more information, go to the <a href=
280 
	 * "http://docs.amazonwebservices.com/ses/latest/DeveloperGuide">Amazon SES Developer Guide</a>.
281 
	 * </p>
282 
	 * The total size of the message cannot exceed 10 MB. This includes any attachments that are part
283 
	 * of the message.
284 
	 *
285 
	 * Amazon SES has a limit on the total number of recipients per message: The combined number of
286 
	 * To:, CC: and BCC: email addresses cannot exceed 50. If you need to send an email message to a
287 
	 * larger audience, you can divide your recipient list into groups of 50 or fewer, and then call
288 
	 * Amazon SES repeatedly to send the message to each group.
289 
	 *
290 
	 * For every message that you send, the total number of recipients (To:, CC: and BCC:) is counted
291 
	 * against your <em>sending quota</em> - the maximum number of emails you can send in a 24-hour
292 
	 * period. For information about your sending quota, go to the "Managing Your Sending Activity"
293 
	 * section of the <a href="http://docs.amazonwebservices.com/ses/latest/DeveloperGuide">Amazon SES
294 
	 * Developer Guide</a>.
295 
	 *
296 
	 * @param array $raw_message (Required) The raw text of the message. The client is responsible for ensuring the following: <ul><li>Message must contain a header and a body, separated by a blank line.</li><li>All required header fields must be present.</li><li>Each part of a multipart MIME message must be formatted properly.</li><li>MIME content types must be among those supported by Amazon SES. Refer to the <a href="http://docs.amazonwebservices.com/ses/latest/DeveloperGuide">Amazon SES Developer Guide</a> for more details.</li><li>Content must be base64-encoded, if MIME requires it.</li></ul> <ul>
297 
	 * 	<li><code>x</code> - <code>array</code> - Optional - This represents a simple array index. <ul>
298 
	 * 		<li><code>Data</code> - <code>blob</code> - Required - The raw data of the message. The client must ensure that the message format complies with Internet email standards regarding email header fields, MIME types, MIME encoding, and base64 encoding (if necessary). For more information, go to the <a href="http://docs.amazonwebservices.com/ses/latest/DeveloperGuide">Amazon SES Developer Guide</a>.</li>
299 
	 * 	</ul></li>
300 
	 * </ul>
301 
	 * @param array $opt (Optional) An associative array of parameters that can have the following keys: <ul>
302 
	 * 	<li><code>Source</code> - <code>string</code> - Optional - The sender's email address. <p class="note">If you specify the <code>Source</code> parameter, then bounce notifications and complaints will be sent to this email address. This takes precedence over any <em>Return-Path</em> header that you might include in the raw text of the message.</p></li>
303 
	 * 	<li><code>Destinations</code> - <code>string|array</code> - Optional - A list of destinations for the message. Pass a string for a single value, or an indexed array for multiple values.</li>
304 
	 * 	<li><code>curlopts</code> - <code>array</code> - Optional - A set of values to pass directly into <code>curl_setopt()</code>, where the key is a pre-defined <code>CURLOPT_*</code> constant.</li>
305 
	 * 	<li><code>returnCurlHandle</code> - <code>boolean</code> - Optional - A private toggle specifying that the cURL handle be returned rather than actually completing the request. This toggle is useful for manually managed batch requests.</li></ul>
306 
	 * @return CFResponse A <CFResponse> object containing a parsed HTTP response.
307 
	 */
308 
	public function send_raw_email($raw_message, $opt = null)
309 
	{
310 
		if (!$opt) $opt = array();
311 
 
312 
		// Required map (non-list)
313 
		$opt = array_merge($opt, CFComplexType::map(array(
314 
			'RawMessage' => (is_array($raw_message) ? $raw_message : array($raw_message))
315 
		), 'member'));
316 
 
317 
		// Optional list (non-map)
318 
		if (isset($opt['Destinations']))
319 
		{
320 
			$opt = array_merge($opt, CFComplexType::map(array(
321 
				'Destinations' => (is_array($opt['Destinations']) ? $opt['Destinations'] : array($opt['Destinations']))
322 
			), 'member'));
323 
			unset($opt['Destinations']);
324 
		}
325 
 
326 
		return $this->authenticate('SendRawEmail', $opt);
327 
	}
328 
 
329 
	/**
330 
	 * Verifies an email address. This action causes a confirmation email message to be sent to the
331 
	 * specified address.
332 
	 *
333 
	 * @param string $email_address (Required) The email address to be verified.
334 
	 * @param array $opt (Optional) An associative array of parameters that can have the following keys: <ul>
335 
	 * 	<li><code>curlopts</code> - <code>array</code> - Optional - A set of values to pass directly into <code>curl_setopt()</code>, where the key is a pre-defined <code>CURLOPT_*</code> constant.</li>
336 
	 * 	<li><code>returnCurlHandle</code> - <code>boolean</code> - Optional - A private toggle specifying that the cURL handle be returned rather than actually completing the request. This toggle is useful for manually managed batch requests.</li></ul>
337 
	 * @return CFResponse A <CFResponse> object containing a parsed HTTP response.
338 
	 */
339 
	public function verify_email_address($email_address, $opt = null)
340 
	{
341 
		if (!$opt) $opt = array();
342 
		$opt['EmailAddress'] = $email_address;
343 
 
344 
		return $this->authenticate('VerifyEmailAddress', $opt);
345 
	}
346 
}
347 
 
348 
 
349 
/*%******************************************************************************************%*/
350 
// EXCEPTIONS
351 
 
352 
class SES_Exception extends Exception {}