Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 SendGrid
Octocat-spinner-32 Test
Octocat-spinner-32 examples
Octocat-spinner-32 lib
Octocat-spinner-32 .gitignore
Octocat-spinner-32 README.md
Octocat-spinner-32 SendGrid.php
Octocat-spinner-32 SendGrid_loader.php
README.md

sendgrid-php

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

License

Licensed under the MIT License.

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/.

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

Mail 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.

Mail Usage

To begin using this library, you must first include it

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

Then, 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('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)

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

Or

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

Using Categories

Categories are used to group email statistics provided by SendGrid

To use a category, simply set the category name

$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.

File attachments are limited to 7 MB per file.

$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

$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.

$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%", array("Mile Square Park", "Platform 4 3/4"))->
       addSection("%home%", array("The Robinsons"));

Using Unique Arguments

Unique Arguments are used for tracking purposes

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

Using Filter Settings

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

$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.

$mail = new SendGrid\Mail();
$mail->addTo('foo@bar.com')->
       ...
       addHeader("category", "My New Category");
Something went wrong with that request. Please try again.