1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
|
# SparkPost PHP SDK
The official PHP binding for your favorite SparkPost APIs!
Before using this library, you must have a valid API Key.
To get an API Key, please log in to your SparkPost account and generate one in the Settings page.
## Installation
The recommended way to install the SparkPost PHP SDK is through composer.
```
# Install Composer
curl -sS https://getcomposer.org/installer | php
```
Next, run the Composer command to install the SparkPost PHP SDK:
```
composer require sparkpost/php-sparkpost
```
After installing, you need to require Composer's autoloader:
```
require 'vendor/autoload.php';
```
## Getting Started: Your First Mailing
```
SparkPost::setConfig(["key"=>"YOUR API KEY"]);
try {
// Build your email and send it!
Transmission::send(array('campaign'=>'first-mailing',
'from'=>'you@your-company.com',
'subject'=>'First SDK Mailing',
'html'=>'<html><body><h1>Congratulations, {{name}}!</h1><p>You just sent your very first mailing!</p></body></html>',
'text'=>'Congratulations, {{name}}!! You just sent your very first mailing!',
'substitutionData'=>array('name'=>'YOUR FIRST NAME'),
'recipients'=>array(array('address'=>array('name'=>'YOUR FULL NAME', 'email'=>'YOUR EMAIL ADDRESS' )))
));
echo 'Woohoo! You just sent your first mailing!';
} catch (Exception $err) {
echo 'Whoops! Something went wrong';
var_dump($err);
}
```
## Learn More
* For more detailed examples, check our examples:
* [Transmissions](https://github.com/SparkPost/php-sparkpost/tree/master/examples/transmission)
* Read our REST API documentation - <http://www.sparkpost.com/docs/introduction>
## Field Descriptions
### Transmissions
| Field Name | Required? | Description | Data Type |
| ------------ | ----------- | ------------- | ----------- |
| description | no | Field for describing what this transmission is for the user | String |
| campaign | no | Field for assigning a given transmission to a specific campaign, which is a logical container for similar transmissions | String |
| metadata | no | Field for adding arbitrary key/value pairs which will be included in open/click tracking | Object (Simple) |
| substitutionData | no | Field for adding transmission level substitution data, which can be used in a variety of fields and in content | Object (Complex) |
| trackOpens | no | Field for enabling/disabling transmission level open tracking (default: true) | Boolean |
| trackClicks | no | Field for enabling/disabling transmission level click tracking (default: true) | Boolean |
| useDraftTemplate | no | Field for allowing the sending of a transmission using a draft of a stored template (default: false) | Boolean |
| replyTo | no | Field for specifying the email address that should be used when a recipient hits the reply button | String |
| subject | yes | Field for setting the subject line of a given transmission | String |
| from | yes | Field for setting the from line of a given transmission | String or Object |
| html | yes** | Field for setting the HTML content of a given transmission | String |
| text | yes** | Field for setting the Plain Text content of a given transmission | String |
| rfc822 | no** | Field for setting the RFC-822 encoded content of a given transmission | String |
| template | no** | Field for specifying the Template ID of a stored template to be used when sending a given transmission | String |
| customHeaders | no | Field for specifying additional headers to be applied to a given transmission (other than Subject, From, To, and Reply-To) | Object (Simple) |
| recipients | yes** | Field for specifying who a given transmission should be sent to | Array of Objects |
| recipientList | no** | Field for specifying a stored recipient list ID to be used for a given transmission | String |
** - If using inline content then html or text are required. If using RFC-822 Inline Content, then rfc822 is required. If using a stored recipient list, then recipientList is required. If using a stored template, then template is required.
## Tips and Tricks
### General
* You _must_ provide at least an API key when instantiating the SparkPost Library - `[ 'key'=>'184ac5480cfdd2bb2859e4476d2e5b1d2bad079bf' ]`
* The SDK's features are namespaced under the various SparkPost API names.
### Transmissions
* If you specify a stored recipient list and inline recipients in a Transmission, you will recieve an error.
* If you specify HTML and/or Plain Text content and then provide RFC-822 encoded content, you will receive an error.
* RFC-822 content is not valid with any other content type.
* If you specify a stored template and also provide inline content via `html` or `text`, you will receive an error.
* By default, open and click tracking are enabled for a transmission.
* By default, a transmission will use the published version of a stored template.
## Development
### Setup
Run `composer install` inside the directory to install dependecies and development tools.
### Testing
Once all the dependencies are installed, you can execute the unit tests using `vendor/bin/phpunit --bootstrap test/unit/bootstrap.php ./test/unit`.
If you're interested in code coverage, you can add the `--coverage` flag for phpunit like so: ```phpunit --coverage-html test/output/report --bootstrap test/unit/bootstrap.php ./test/unit```
### Contributing
Guidelines for adding issues
Submitting pull requests
Signing our CLA
Our coding standards
|
