rodchyn/sendgrid-php-sdk

Sendgrid PHP SDK

sendgrid-php

This library allows you to quickly and easily send emails through SendGrid using PHP., _(*1)

License

Licensed under the MIT License., _(*2)

Install

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

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/., _(*3)

This library implements a common interface to make it very easy to use either API., _(*4)

Mail Pre-Usage

Before we begin using the library, its important to understand a few things about the library architecture..., _(*5)

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

  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 :, _(*7)

  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.

Mail Usage

To begin using this library, you must first include it, _(*8)

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

Then, initialize the SendGrid object with your SendGrid credentials, _(*9)

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

Create a new SendGrid Mail object and add your message details, _(*10)

$mail = new SendGrid\Mail();
$mail->addTo('foo@bar.com')->
       setFrom('me@bar.com')->
       setSubject('Subject goes here')->
       setText('Hello World!')->
       setHtml('<strong>Hello World!</strong>');

Send it using the API of your choice (SMTP or Web), _(*11)

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

Or, _(*12)

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

Using Categories

Categories are used to group email statistics provided by SendGrid., _(*13)

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

$mail = new SendGrid\Mail();
$mail->addTo('foo@bar.com')->
       ...
       addCategory("Category 1")->
       addCategory("Category 2");

Using Attachments

Attachments are currently file based only, with future plans for an in memory implementation as well., _(*15)

File attachments are limited to 7 MB per file., _(*16)

$mail = new SendGrid\Mail();
$mail->addTo('foo@bar.com')->
       ...
       addAttachment("../path/to/file.txt");    

Using Substitutions

Substitutions can be used to customize multi-recipient emails, and tailor them for the user, _(*17)

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

Using Sections

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

$mail = new SendGrid\Mail();
$mail->addTo('john@somewhere.com')->
       addTo("harry@somewhere.com")->
       addTo("Bob@somewhere.com")->
       ...
       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");

Using Unique Arguments

Unique Arguments are used for tracking purposes, _(*19)

$mail = new SendGrid\Mail();
$mail->addTo('foo@bar.com')->
       ...
       addUniqueArgument("Customer", "Someone")->
       addUniqueArgument("location", "Somewhere");

Using Filter Settings

Filter Settings are used to enable and disable apps, and to pass parameters to those apps., _(*20)

$mail = new SendGrid\Mail();
$mail->addTo('foo@bar.com')->
       ...
       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>");

Using Headers

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

$mail = new SendGrid\Mail();
$mail->addTo('foo@bar.com')->
       ...
       addHeader("category", "My New Category");