This library allows you to quickly and easily send emails from Google App Engine through SendGrid using PHP.
Important: This library requires PHP 5.3 or higher.
$sendgrid = new SendGrid\SendGrid('username', 'password');
$mail = new SendGrid\Mail();
$mail->addTo('foo@bar.com')->
addTo('dude@bar.com')->
setFrom('me@bar.com')->
setSubject('Subject goes here')->
setText('Hello World!')->
setHtml('<strong>Hello World!</strong>');
$sendgrid->send($mail);
git clone https://github.com/sendgrid/sendgrid-google-php.git
Then require the autoloader from your php script:
require '../path/to/sendgrid-google-php/SendGrid_loader.php';
SendGrid provides SendGrid library for sending email.
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:
- set - reset the data, and initialize it to the given element. This will destroy previous data
- set (List) - for array based elements, we provide a way of passing the entire array in at once. This will also destroy previous data.
- add - append data to the list of elements.
- Sending an email is as simple as :
- Creating a SendGrid Instance
- Creating a SendGrid Mail object, and setting its data
- Sending the mail using Web API.
To begin using this library, initialize the SendGrid object with your SendGrid credentials.
$sendgrid = new SendGrid\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>');
$sendgrid->send($mail);
You can add one or multiple TO addresses using addTo
.
$mail = new SendGrid\Mail();
$mail->addTo('foo@bar.com')->
addTo('another@another.com');
$sendgrid->send($mail);
If you prefer, you can add multiple TO addresses as an array using the setTos
method. This will unset any previous addTo
s you appended.
$mail = new SendGrid\Mail();
$emails = array("foo@bar.com", "another@another.com", "other@other.com");
$mail->setTos($emails);
$sendgrid->send($mail);
Sometimes you might find yourself wanting to list the currently set Tos. You can do that with getTos
.
$mail = new SendGrid\Mail();
$mail->addTo('foo@bar.com');
$mail->getTos();
You might also find yourself wanting to remove a single TO from your set list of TOs. You can do that with removeTo
. You can pass a string or regex to the removeTo method.
$mail = new SendGrid\Mail();
$mail->addTo('foo@bar.com');
$mail->removeTo('foo@bar.com');
$mail = new SendGrid\Mail();
$mail->setFrom('foo@bar.com');
$sendgrid->send($mail);
$mail = new SendGrid\Mail();
$mail->setFrom('foo@bar.com');
$mail->setFromName('Foo Bar');
$mail->setFrom('other@example.com');
$mail->setFromName('Other Guy');
$sendgrid->send($mail);
$mail = new SendGrid\Mail();
$mail->setReplyTo('foo@bar.com');
$sendgrid->send($mail);
$mail = new SendGrid\Mail();
$mail->addCc('foo@bar.com');
$sendgrid->send($mail);
Use multiple addTo
s as a superior alternative to setBcc
.
$mail = new SendGrid\Mail();
$mail->addTo('foo@bar.com')->
addTo('someotheraddress@bar.com')->
addTo('another@another.com')->
...
But if you do still have a need for Bcc you can do the following.
$mail = new SendGrid\Mail();
$mail->addBcc('foo@bar.com');
$sendgrid->send($mail);
$mail = new SendGrid\Mail();
$mail->setSubject('This is a subject');
$sendgrid->send($mail);
$mail = new SendGrid\Mail();
$mail->setText('This is some text');
$sendgrid->send($mail);
$mail = new SendGrid\Mail();
$mail->setHtml('<h1>This is an html email</h1>');
$sendgrid->send($mail);
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('foo@bar.com')->
...
addCategory("Category 1")->
addCategory("Category 2");
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");
Important Gotcha: setBcc
is not supported with attachments. This is by design. Instead use multiple addTo
s. Each user will receive their own personalized email with that setup, and only see their own email.
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 addTo
s because setBcc is not supported with attachments. This is by design.
So just remember, when thinking 'bcc', instead use multiple addTo
s.
There are two handy helper methods for setting the From-Name and Reply-To for a message
$mail = new SendGrid\Mail();
$mail->addTo('foo@bar.com')->
setReplyTo('someone.else@example.com')->
setFromName('John Doe')->
...
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"));
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('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");
Unique Arguments are used for tracking purposes
$mail = new SendGrid\Mail();
$mail->addTo('foo@bar.com')->
...
addUniqueArgument("Customer", "Someone")->
addUniqueArgument("location", "Somewhere");
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>");
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");
Sometimes you might want to send 1,000s of emails in one request. You can do that. It is recommended you break each batch up in 1,000 increements. So if you need to send to 5,000 emails, then you'd break this into a loop of 1,000 emails at a time.
$sendgrid = new SendGrid(SENDGRID_USERNAME, SENDGRID_PASSWORD);
$mail = new SendGrid\Mail();
$recipients = array("alpha@mailinator.com", "beta@mailinator.com", "zeta@mailinator.com");
$names = array("Alpha", "Beta", "Zeta");
$mail-> setFrom("from@mailinator.com")->
setSubject('[sendgrid-php-batch-email]')->
setTos($recipients)->
addSubstitution("%name%", $names)->
setText("Hey %name, we have an email for you")->
setHtml("<h1>Hey %name%, we have an email for you</h1>");
$result = $sendgrid->web->send($mail);
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Added some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request