This library allows you to quickly and easily send emails through SendGrid using PHP.

$sendgrid = new SendGrid('username', 'password');
$mail     = new SendGrid\Mail();
$mail->addTo('[email protected]')->
       addTo('[email protected]')->
       setFrom('[email protected]')->
       setSubject('Subject goes here')->
       setText('Hello World!')->
       setHtml('<strong>Hello World!</strong>');

$sendgrid->smtp->send($mail);

Installation

The following recommended installation requires composer. If you are unfamiliar with composer see the composer installation instructions.

Add the following to your composer.json file:

{  
  "require": {
    "sendgrid/sendgrid": "~1.0.0"
  }
}

Install sendgrid-php and its dependencies:

composer install

Load sendgrid-php and its dependencies into your project:

require 'vendor/autoload.php';

Alternative Installation

If you choose not to use composer you can do the following alternative installation using git:

git clone https://github.com/sendgrid/sendgrid-php.git

Then require the autoloader from your php script:

require '../path/to/sendgrid-php/SendGrid_loader.php';

Finally, install SwiftMailer using pear.

pear channel-discover pear.swiftmailer.org
pear install swift/swift

Note: If you do not plan on sending using SMTP, you can skip installation of swiftmailer.

SendGrid APIs

SendGrid provides two methods of sending email: the Web API, and SMTP API. SendGrid recommends using the SMTP API for sending emails. For an explanation of the benefits of each, refer to http://docs.sendgrid.com/documentation/get-started/integrate/examples/smtp-vs-rest/.

This library implements a common interface to make it very easy to use either API.

Pre-Usage

Before we begin using the library, its important to understand a few things about the library architecture...

• The SendGrid Mail object is the means of setting mail data. In general, data can be set in three ways for most elements:

  1. set - reset the data, and initialize it to the given element. This will destroy previous data
  2. set (List) - for array based elements, we provide a way of passing the entire array in at once. This will also destroy previous data.
  3. add - append data to the list of elements.

• Sending an email is as simple as :

  1. Creating a SendGrid Instance
  2. Creating a SendGrid Mail object, and setting its data
  3. Sending the mail using either SMTP API or Web API.

Usage

To begin using this library, initialize the SendGrid object with your SendGrid credentials.

$sendgrid = new SendGrid('username', 'password');

Create a new SendGrid Mail object and add your message details.

$mail = new SendGrid\Mail();
$mail->addTo('[email protected]')->
       setFrom('[email protected]')->
       setSubject('Subject goes here')->
       setText('Hello World!')->
       setHtml('<strong>Hello World!</strong>');

Send it using the API of your choice (SMTP or Web)

$sendgrid->smtp->send($mail);

Or

$sendgrid->web->send($mail);

Categories

Categories are used to group email statistics provided by SendGrid.

To use a category, simply set the category name. Note: there is a maximum of 10 categories per email.

$mail = new SendGrid\Mail();
$mail->addTo('[email protected]')->
       ...
       addCategory("Category 1")->
       addCategory("Category 2");

Attachments

Attachments are currently file based only, with future plans for an in memory implementation as well.

File attachments are limited to 7 MB per file.

$mail = new SendGrid\Mail();
$mail->addTo('[email protected]')->
       ...
       addAttachment("../path/to/file.txt");    

Important Gotcha: setBcc is not supported with attachments. This is by design. Instead use multiple addTos. Each user will receive their own personalized email with that setup, and only see their own email.

Bcc

Use multiple addTos as a superior alternative to setBcc.

$mail = new SendGrid\Mail();
$mail->addTo('[email protected]')->
       addTo('[email protected]')->
       addTo('[email protected]')->
       ...

Standard setBcc will hide who the email is addressed to. If you use the multiple addTo, each user will receive a personalized email showing *only their email. This is more friendly and more personal. Additionally, it is a good idea to use multiple addTos because setBcc is not supported with attachments. This is by design.

So just remember, when thinking 'bcc', instead use multiple addTos.

From-Name and Reply-To

There are two handy helper methods for setting the From-Name and Reply-To for a message

$mail = new SendGrid\Mail();
$mail->addTo('[email protected]')->
       setReplyTo('[email protected]')->
       setFromName('John Doe')->
       ...

Substitutions

Substitutions can be used to customize multi-recipient emails, and tailor them for the user

$mail = new SendGrid\Mail();
$mail->addTo('[email protected]')->
       addTo("[email protected]")->
       addTo("[email protected]")->
       ...
       setHtml("Hey %name%, we've seen that you've been gone for a while")->
       addSubstitution("%name%", array("John", "Harry", "Bob"));

Sections

Sections can be used to further customize messages for the end users. A section is only useful in conjunction with a substition value.

$mail = new SendGrid\Mail();
$mail->addTo('[email protected]')->
       addTo("[email protected]")->
       addTo("[email protected]")->
       ...
       setHtml("Hey %name%, you work at %place%")->
       addSubstitution("%name%", array("John", "Harry", "Bob"))->
       addSubstitution("%place%", array("%office%", "%office%", "%home%"))->
       addSection("%office%", "an office")->
       addSection("%home%", "your house");

Unique Arguments

Unique Arguments are used for tracking purposes

$mail = new SendGrid\Mail();
$mail->addTo('[email protected]')->
       ...
       addUniqueArgument("Customer", "Someone")->
       addUniqueArgument("location", "Somewhere");

Filter Settings

Filter Settings are used to enable and disable apps, and to pass parameters to those apps.

$mail = new SendGrid\Mail();
$mail->addTo('[email protected]')->
       ...
       addFilterSetting("gravatar", "enable", 1)->
       addFilterSetting("footer", "enable", 1)->
       addFilterSetting("footer", "text/plain", "Here is a plain text footer")->
       addFilterSetting("footer", "text/html", "<p style='color:red;'>Here is an HTML footer</p>");

Headers

Headers can be used to add existing sendgrid functionality (such as for categories or filters), or custom headers can be added as necessary.

$mail = new SendGrid\Mail();
$mail->addTo('[email protected]')->
       ...
       addHeader("category", "My New Category");

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Added some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Running Tests

The existing tests in the Test directory can be run using PHPUnit with the following command:

composer update --dev
vendor/bin/phpunit Test/
```

or if you already have PHPUnit installed globally.

```bash
phpunit Test/
```

## Known Issues

* When using the smtp version (which is built on top of swiftmailer), any FROM names with parentheses will have the content of the parentheses stripped out. If this happens please use the web version of the library. Read more about this in [issue #27](https://github.com/sendgrid/sendgrid-php/issues/27).