Notice: This resource is no longer being actively maintained and as a result some information may be out of date or inaccurate. Please see for technical instructions or for support related concerns.
RUN@cloud » SendGrid Service

SendGrid Service

Last modified by Cyrille Le Clerc on 2014/03/15 19:25

CloudBees now supports sending mail from applications with the SendGrid Service for RUN@cloud. To activate your subscription, go to SendGrid in grandcentral.

Once the subscription has been activated, go to the Sendgrid page (click on the SendGrid service in the Services page) to configure your service.

SendGrid Credentials

For most application stacks, your SendGrid credentials are automatically injected into the application as System properties (for Java) or environment variables.  The injected names are SENDGRID_USERNAME and SENDGRID_PASSWORD.

If you need to get direct access to your password from outside your application, you can use the following Bees SDK command:

bees service:info sendgrid

Configure JavaEE Applications

A default mail session is defined for your application running in a Tomcat cloud container under the "mail/SendGrid" JNDI name. The session is configured with your SendGrid subscription information for a TLS/plain connection on port 587.

You can then use the mail session (mail/SendGrid) resource from your application by retrieving it from the environment context:

            Context initCtx = new InitialContext();
            Session session = (Session) initCtx.lookup("java:comp/env/mail/SendGrid");

Then send emails via the standard JavaMail API:

            Message message = new MimeMessage(session);
            message.setFrom(new InternetAddress(FROM);
            InternetAddress to[] = new InternetAddress[1];
            to[0] = new InternetAddress(TO);
            message.setRecipients(Message.RecipientType.TO, to);
            message.setContent(CONTENT, "text/plain");

Configure other Applications

On alternative application stack that don't use JNDI to get a Mail Session, or don't use JavaMail at all, the SendGrid subscription information is also available as system properties:




as a sample, configuring a Play! application.conf to use SendGrid is :${SENDGRID_SMTP_HOST}

Customize the default Mail Session

The default "mail/SendGrid" mail session can be customized by defining session resource parameters via the cloudbees-web.xml

For example: to turn on mail debugging mode

<?xml version="1.0"?>
<cloudbees-web-app xmlns="http:~/~/">     
   <resource name="mail/SendGrid" auth="Container"  type="javax.mail.Session">
       <param name="mail.debug" value="true" />

Mail Session Alias

If a mail session with a specific name is needed, a mail session alias can be defined as a web.xml resource-ref

For example: to define a mail session JNDI name as "mail/MySession" add the following resource-ref to your web.xml


Custom Mail Session

To create a fully custom java mail session, define a new resource in the WEB-INF/cloudbees-web.xml file.

For example: to define a mail session that uses a SSL connection to the mail server

<?xml version="1.0"?>
<cloudbees-web-app xmlns="http:~/~/">     
   <resource name="mail/Session" auth="Container"  type="javax.mail.Session">
       <param name="mail.transport.protocol" value="smtps" />
       <param name="" value="" />
       <param name="mail.smtp.port" value="465" />
       <param name="mail.smtp.auth" value="true" />
       <param name="mail.smtp.ssl.enable" value="true" />
       <param name="mail.smtp.user" value="sendgrid account user name" />
       <param name="password" value="sendgrid account password" />
       <param name="mail.smtp.socketFactory.class" value="" />
       <param name="mail.smtp.socketFactory.fallback" value="false" />
       <param name="mail.smtp.quitwait" value="false" />

Sending mail with Wildfly

See the Wildfly 8 ClickStack page.

Sending mail with JBoss

The JBoss Web Profile does not support mail session JNDI access. To use SendGrid with JBoss you need to instantiate your own mail client. The smtp host and credentials are available via System Properties

Example java mail client:
    private void mailClient(String from, String to, String subject, String content) {
        SMTP_HOST_NAME = System.getProperty("SENDGRID_SMTP_HOST");
        SMTP_AUTH_USER = System.getProperty("SENDGRID_USERNAME");
        SMTP_AUTH_PWD = System.getProperty("SENDGRID_PASSWORD");        

        Properties props = new Properties();
        props.put("mail.transport.protocol", "smtp");
        props.put("", SMTP_HOST_NAME);
        props.put("mail.smtp.port", 587);
        props.put("mail.smtp.auth", "true");

        Authenticator auth = new SMTPAuthenticator();
        Session mailSession = Session.getDefaultInstance(props, auth);
        Transport transport = null;
       try {
            transport = mailSession.getTransport();

            MimeMessage message = new MimeMessage(mailSession);

            Multipart multipart = new MimeMultipart("alternative");

            BodyPart part1 = new MimeBodyPart();

            BodyPart part2 = new MimeBodyPart();
            part2.setContent("<strong>" + content + "</strong>", "text/html");



            message.setFrom(new InternetAddress(from));
            InternetAddress toAddress[] = new InternetAddress[1];
            toAddress[0] = new InternetAddress(to);
            message.setRecipients(Message.RecipientType.TO, toAddress);

            transport.sendMessage(message, message.getRecipients(Message.RecipientType.TO));
        } catch (Exception e) {
        } finally {
           if (transport != null)
               try {
                } catch (MessagingException e) {

    private class SMTPAuthenticator extends javax.mail.Authenticator {
        public PasswordAuthentication getPasswordAuthentication() {
           String username = SMTP_AUTH_USER;
           String password = SMTP_AUTH_PWD;
          return new PasswordAuthentication(username, password);

Created by Fabian Donze on 2011/11/10 14:01