SendGrid

SendGrid’s cloud-based email infrastructure relieves businesses of the cost and complexity of maintaining custom email systems. SendGrid provides reliable delivery, scalability and real-time analytics along with flexible APIs that make custom integration a breeze.

Dashboard
Integrating the Service With Your App
Code Examples
Additional Resources
Support

Dashboard

The SendGrid dashboard can be accessed by visiting: sendgrid.com/login

SendGrid offers statistics on a number of different metrics to report on what is happening with your messages including:

Alerts: SendGrid will trigger an alert to send you based on triggers you set within SendGrid.
Categories: SendGrid will allow you to filter email statistics based on specific categories you add to your emails.
Email Activity: A page within your account that allows you to see recent stats on your sent emails.
Email Error Messages: All of the Error messages that you can expect from SendGrid.
Email Reports: View and export reports about your email activity.

Integrating the Service With Your App

Once you have subscribed to this service and located your credentials, you will need to configure your application to use the credentials for your service.

SendGrid Environment Variables

We recommend setting the following environment variables within your application runtime to connect the service to your app:

Variable Name

Example Value

SENDGRID_HOSTNAME

smtp.sendgrid.net

SENDGRID_PASSWORD

adsRvqPZra

SENDGRID_USERNAME

DM12KPNLIq

Use the OpenShift client tools to set environment variables to make your credentials available within your application runtime:

$ rhc env set SENDGRID_HOSTNAME=VALUE -a App_Name
$ rhc env set SENDGRID_PASSWORD=VALUE -a App_Name
$ rhc env set SENDGRID_USERNAME=VALUE -a App_Name

Code Examples

The following code examples show how to easily configure your application to send email with SendGrid.

Java
Node.js
Perl
PHP
PHP: Using Composer
PHP: CodeIgniter
PHP: Laravel
PHP: WordPress
Python
Python: Django
Ruby
Ruby: Using the Mail Gem

Java

Add the following dependencies to your pom.xml file:

...
<dependencies>
  ...
  <dependency>
    <groupId>com.sendgrid</groupId>
    <artifactId>sendgrid-java</artifactId>
    <version>2.1.0</version>
  </dependency>
  <dependency>
    <groupId>org.json</groupId>
    <artifactId>json</artifactId>
    <version>20141113</version>
  </dependency>
</dependencies>
...

Now you’re ready to use SendGrid within your application:

// using SendGrid's Java Library - https://github.com/sendgrid/sendgrid-java
import com.sendgrid.*;

public class SendGridExample {
  public static void main(String[] args) {
    SendGrid sendgrid = new SendGrid(System.getenv('SENDGRID_USERNAME'), System.getenv('SENDGRID_PASSWORD'));

    SendGrid.Email email = new SendGrid.Email();

    email.addTo("[email protected]");
    email.setFrom("[email protected]");
    email.setSubject("Sending with SendGrid is Fun");
    email.setHtml("and easy to do anywhere, even with Java");

    SendGrid.Response response = sendgrid.send(email);
  }
}

For more information see the SendGrid Java client library on GitHub.

Node.js

Add the following dependency to your package.json file:

{
  ...
  "dependencies": {
    ...
    "sendgrid": "1.6.0"
  }
}

Now you’re ready to use SendGrid within your application:

// using SendGrid's Node.js Library - https://github.com/sendgrid/sendgrid-nodejs
var sendgrid = require("sendgrid")(process.env.SENDGRID_USERNAME, process.env.SENDGRID_PASSWORD);
var email = new sendgrid.Email();

email.addTo("[email protected]");
email.setFrom("[email protected]");
email.setSubject("Sending with SendGrid is Fun");
email.setHtml("and easy to do anywhere, even with Node.js");

sendgrid.send(email);

Perl

Add the following to your .openshift/cpan.txt file:

git://github.com/sendgrid/sendgrid-perl.git

Now you’re ready to use SendGrid within your application:

# using SendGrid's Perl Library - https://github.com/sendgrid/sendgrid-perl
use Mail::SendGrid;
use Mail::SendGrid::Transport::REST;

my $sendgrid = Mail::SendGrid->new(
  from => "[email protected]",
  to => "[email protected]",
  subject => "Sending with SendGrid is Fun",
  html => "and easy to do anywhere, even with Perl"
);

Mail::SendGrid::Transport::REST->new( username => $ENV{'SENDGRID_USERNAME'}, password => $ENV{'SENDGRID_PASSWORD'}} );

For more information see the SendGrid Perl client library on GitHub.

PHP

Download and unpack the latest packaged release of SendGrid PHP.

Then require the library from package:

require("path/to/sendgrid-php/sendgrid-php.php");

Learn more about the default include path for OpenShift PHP applications.

Now you’re ready to use SendGrid within your application:

$sendgrid = new SendGrid(getenv('SENDGRID_USERNAME'), getenv('SENDGRID_PASSWORD'));
$email    = new SendGrid\Email();

$email->addTo("[email protected]")
      ->setFrom("[email protected]")
      ->setSubject("Sending with SendGrid is Fun")
      ->setHtml("and easy to do anywhere, even with PHP");

$sendgrid->send($email);

For more information see the SendGrid PHP client library on GitHub.

PHP: Using Composer

Create an empty file named use_composer in .openshift/markers:

$ touch .openshift/markers/use_composer

Adding the use_composer marker file to .openshift/markers will enable running composer install on each build automatically. Learn more about PHP markers on OpenShift.

Add SendGrid to your composer.json file in your application’s root directory:

{
  "require": {
    "sendgrid/sendgrid": "2.2.1"
  }
}

Then at the top of your PHP script require the autoloader:

require 'vendor/autoload.php';

Now you’re ready to use SendGrid within your application:

// get account info from OpenShift environment variable
$sendgrid = new SendGrid(getenv('SENDGRID_USERNAME'), getenv('SENDGRID_PASSWORD'));
$email    = new SendGrid\Email();

$email->addTo("[email protected]")
      ->setFrom("[email protected]")
      ->setSubject("Sending with SendGrid is Fun")
      ->setHtml("and easy to do anywhere, even with PHP");

$sendgrid->send($email);

For more information see the SendGrid PHP client library on GitHub.

PHP: CodeIgniter

The following code example shows how to use SendGrid with CodeIgniter’s built-in email library:

$this->load->library('email');

$this->email->initialize(array(
  'protocol' => 'smtp',
  'smtp_host' => getenv('SENDGRID_HOSTNAME'),
  'smtp_user' => getenv('SENDGRID_USERNAME'),
  'smtp_pass' => getenv('SENDGRID_PASSWORD'),
  'smtp_port' => 587,
  'crlf' => "\r\n",
  'newline' => "\r\n"
));

$this->email->from('[email protected]', 'Your Name');
$this->email->to('[email protected]');
$this->email->cc('[email protected]');
$this->email->bcc('[email protected]');
$this->email->subject('Email Test');
$this->email->message('Testing the email class.');
$this->email->send();

echo $this->email->print_debugger();

It is important to use the correct end of lines using "crlf" ⇒ "\r\n" and "newline" ⇒ "\r\n".

See more information on how to use CodeIgniter with SendGrid.

PHP: Laravel

Laravel comes with an email sending library built in, so we just need to set it to use SendGrid over SMTP.

In app/config/mail.php you need to configure these settings:

<?php
return array(
  'driver' => 'smtp',
  'host' => getenv('SENDGRID_HOSTNAME'),
  'port' => 587,
  'from' => array('address' => '[email protected]', 'name' => 'John Smith'),
  'encryption' => 'tls',
  'username' => getenv('SENDGRID_USERNAME'),
  'password' => getenv('SENDGRID_PASSWORD')
);

?>

You can use Laravel’s Mail class just like you normally would, but all email will be sent through SendGrid!

Mail::send('emails.demo', $data, function($message)
{
    $message->to('[email protected]', 'Jane Doe')->subject('This is a demo!');
});

Check out the docs for Laravel’s mailer for details.

PHP: WordPress

Download the Official SendGrid WordPress Plugin.

Extract the zip archive file and move the Plugin folder to the .openshift/plugins directory of your repository (or to your wp-content/plugins folder if you’re not using the default OpenShift WordPress installation).

Add the following code to .openshift/config/wp-config.php in your local repo:

// set credentials
define('SENDGRID_USERNAME', getenv('SENDGRID_USERNAME');
define('SENDGRID_PASSWORD', getenv('SENDGRID_PASSWORD');

// set email related settings
define('SENDGRID_SEND_METHOD', 'api');

Next, add and commit your changes using git:

$ git add .
$ git commit -m "Adds fully configured SendGrid WordPress Plugin"

Deploy your changes to your live WordPress application with git:

$ git push

Next, you’ll need to activate the plugin from the "Plugins" menu in the WordPress admin panel.

Finally, on the SendGrid plugin settings page you can set default values for the "Name", "Sending Address" and the "Reply Address", so that you don’t need to set these headers every time you want to send an email from your application.

configure the SendGrid WordPress plugin settings

That’s it! WordPress emails will now be sent through SendGrid. For more information check out the official plugin page.

Python

Add the following to your pip requirements.txt file located at the root of your repository:

sendgrid>=1.2

Now you’re ready to use SendGrid within your application:

import sendgrid, os

sg = sendgrid.SendGridClient(os.getenv('SENDGRID_USERNAME'), os.getenv('SENDGRID_PASSWORD'))

message = sendgrid.Mail()
message.add_to('John Doe ')
message.set_subject('Example')
message.set_text('Body')
message.set_from('Doe John ')
status, msg = sg.send(message)

For more information see the SendGrid Python client library on GitHub.

Python: Django

Start by adding the following to settings.py:

import os

EMAIL_HOST = os.getenv('SENDGRID_HOSTNAME')
EMAIL_HOST_USER = os.getenv('SENDGRID_USERNAME')
EMAIL_HOST_PASSWORD = os.getenv('SENDGRID_PASSWORD')
EMAIL_PORT = 587
EMAIL_USE_TLS = True

Then to send email you can do the following:

from django.core.mail import send_mail
send_mail('Subject here', 'Here is the message.', '[email protected]', ['[email protected]'], fail_silently=False)

There is more detailed information about sending email over SMTP with Django on the Django project website.

You may also send emails with Django by using the sendgrid-django library, which utilizes the Web API instead of SMTP as the transport mechanism.

Ruby

Add a Gemfile file named Gemfile to the root of your repository:

source 'http://mirror.ops.rhcloud.com/mirror/ruby/'
gem 'sendgrid-ruby'

Use OpenShift’s mirror of rubygems.org as shown above to speed up your deployments.

Next, run bundle install (using Bundler) to create a Gemfile.lock file:

$ bundle install

Now you’re ready to use SendGrid within your application:

require 'sendgrid-ruby'

client = SendGrid::Client.new(api_user: ENV['SENDGRID_USERNAME'], api_key: ENV['SENDGRID_PASSWORD'])

email = SendGrid::Mail.new do |m|
  m.to      = '[email protected]'
  m.from    = '[email protected]'
  m.subject = 'Sending with SendGrid is Fun'
  m.html    = 'and easy to do anywhere, even with Ruby'
end

client.send(email)

For more information see the SendGrid Python client library on GitHub.

Ruby: Using the Mail Gem

The example below shows how to send email plain text and HTML email using Ruby using the Mail gem.

First, add a Gemfile file named Gemfile to the root of your repository:

source 'http://mirror.ops.rhcloud.com/mirror/ruby/'
gem 'mail'

Next, run bundle install (using Bundler) to create a Gemfile.lock file:

$ bundle install

Use OpenShift’s mirror of rubygems.org as shown above to speed up your deployments.

Now you’re ready to use SendGrid with Mail in your application:

require 'mail'

Mail.defaults do
  delivery_method :smtp, { :address   => ENV['SENDGRID_HOSTNAME'],
                           :port      => 587,
                           :domain    => "yourdomain.com",
                           :user_name => ENV['SENDGRID_USERNAME'],
                           :password  => ENV['SENDGRID_PASSWORD'],
                           :authentication => 'plain',
                           :enable_starttls_auto => true }
end

mail = Mail.deliver do
  to '[email protected]'
  from 'Your Name <[email protected]>'
  subject 'This is the subject of your email'
  text_part do
    body 'Hello world in text'
  end
  html_part do
    content_type 'text/html; charset=UTF-8'
    body '<b>Hello world in HTML</b>'
  end
end

Additional Resources

Additional documentation and examples are available at https://sendgrid.com/docs/.

Support

Phone Support: + 1 303 552 0653
Email: [email protected]
Support Portal: https://support.sendgrid.com/