Skip to content

Latest commit

 

History

History
318 lines (255 loc) · 9.48 KB

USE_CASES.md

File metadata and controls

318 lines (255 loc) · 9.48 KB

This documentation provides examples for specific use cases. Please open an issue or make a pull request for any use cases you would like us to document here. Thank you!

Table of Contents

Transactional Templates

For this example, we assume you have created a transactional template in the UI or via the API. Following is the template content we used for testing.

Template ID (replace with your own):

d-2c214ac919e84170b21855cc129b4a5f

Email Subject:

{{subject}}

Template Body:

<html>
  <head>
    <title></title>
  </head>
  <body>
    Hello {{name}},
    <br/><br/>
    I'm glad you are trying out the template feature!
    <br/><br/>
    I hope you are having a great day in {{city}} :)
    <br/><br/>
  </body>
</html>

With Mail Helper Class

import com.sendgrid.*;
import java.io.IOException;

public class Example {
  public static void main(String[] args) throws IOException {
    Mail mail = new Mail();
    mail.setFrom(new Email("[email protected]"));
    mail.setTemplateId("d-2c214ac919e84170b21855cc129b4a5f");

    Personalization personalization = new Personalization();
    personalization.addDynamicTemplateData("subject", "Testing Templates");
    personalization.addDynamicTemplateData("name", "Example User");
    personalization.addDynamicTemplateData("city", "Denver");
    personalization.addTo(new Email("[email protected]"));
    mail.addPersonalization(personalization);
            
    SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));
    Request request = new Request();
    try {
      request.setMethod(Method.POST);
      request.setEndpoint("mail/send");
      request.setBody(mail.build());
      Response response = sg.api(request);
      System.out.println(response.getStatusCode());
      System.out.println(response.getBody());
      System.out.println(response.getHeaders());
    } catch (IOException ex) {
      throw ex;
    }
  }
}

Without Mail Helper Class

import com.sendgrid.*;
import java.io.IOException;

public class Example {
  public static void main(String[] args) throws IOException {
    try {
      SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));
      Request request = new Request();
      request.setMethod(Method.POST);
      request.setEndpoint("mail/send");
      request.setBody("{
        \"from\": {\"email\": \"[email protected]\"},
        \"personalizations\":
        [{
          \"to\": [{\"email\": \"[email protected]\"}],
          \"dynamic_template_data\": {\"subject\": \"Testing Templates\",\"name\": \"Example User\", \"city\": \"Denver\"}
        }],
        \"template_id\": \"d-2c214ac919e84170b21855cc129b4a5f\"}");
      Response response = sg.api(request);
      System.out.println(response.getStatusCode());
      System.out.println(response.getBody());
      System.out.println(response.getHeaders());
    } catch (IOException ex) {
      throw ex;
    }
  }
}

Legacy Templates

For this example, we assume you have created a legacy template. Following is the template content we used for testing.

Template ID (replace with your own):

13b8f94f-bcae-4ec6-b752-70d6cb59f932

Email Subject:

<%subject%>

Template Body:

<html>
  <head>
    <title></title>
  </head>
  <body>
    Hello -name-,
    <br /><br/>
    I'm glad you are trying out the template feature!
    <br /><br/>
    <%body%>
    <br /><br/>
    I hope you are having a great day in -city- :)
    <br /><br/>
  </body>
</html>

With Mail Helper Class

import com.sendgrid.*;
import java.io.IOException;

public class Example {
  public static void main(String[] args) throws IOException {
    Email from = new Email("[email protected]");
    String subject = "I'm replacing the subject tag";
    Email to = new Email("[email protected]");
    Content content = new Content("text/html", "I'm replacing the <strong>body tag</strong>");
    Mail mail = new Mail(from, subject, to, content);
    mail.personalization.get(0).addSubstitution("-name-", "Example User");
    mail.personalization.get(0).addSubstitution("-city-", "Denver");
    mail.setTemplateId("13b8f94f-bcae-4ec6-b752-70d6cb59f932");

    SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));
    Request request = new Request();
    try {
      request.setMethod(Method.POST);
      request.setEndpoint("mail/send");
      request.setBody(mail.build());
      Response response = sg.api(request);
      System.out.println(response.getStatusCode());
      System.out.println(response.getBody());
      System.out.println(response.getHeaders());
    } catch (IOException ex) {
      throw ex;
    }
  }
}

Without Mail Helper Class

import com.sendgrid.*;
import java.io.IOException;

public class Example {
  public static void main(String[] args) throws IOException {
    try {
      SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY"));
      Request request = new Request();
      request.setMethod(Method.POST);
      request.setEndpoint("mail/send");
      request.setBody("{
        \"personalizations\":
        [{
          \"to\": [{\"email\": \"[email protected]\"}],
          \"substitutions\": {\"-name-\": \"Example User\", \"-city-\": \"Denver\"},
          \"subject\": \"Hello World from the Twilio SendGrid Java Library!\"
        }],
        \"from\": {\"email\": \"[email protected]\"},
        \"content\":
        [{
          \"type\": \"text/html\",
          \"value\": \"I'm replacing the <strong>body tag</strong>\"
        }]
        ,\"template_id\": \"13b8f94f-bcae-4ec6-b752-70d6cb59f932\"}");
      Response response = sg.api(request);
      System.out.println(response.getStatusCode());
      System.out.println(response.getBody());
      System.out.println(response.getHeaders());
    } catch (IOException ex) {
      throw ex;
    }
  }
}

How to Setup a Domain Authentication

You can find documentation for how to setup a domain authentication via the UI here and via API here.

Find more information about all of Twilio SendGrid's authentication related documentation here.

How to View Email Statistics

You can find documentation for how to view your email statistics via the UI here and via API here.

Alternatively, we can post events to a URL of your choice via our Event Webhook about events that occur as Twilio SendGrid processes your email.

Send a SMS Message

Following are the steps to add Twilio SMS to your app:

1. Obtain a Free Twilio Account

Sign up for a free Twilio account here.

2. Update Your Environment Variables

You can obtain your Account Sid and Auth Token from twilio.com/console.

Mac

echo "export TWILIO_ACCOUNT_SID='YOUR_TWILIO_ACCOUNT_SID'" > twilio.env
echo "export TWILIO_AUTH_TOKEN='YOUR_TWILIO_AUTH_TOKEN'" >> twilio.env
echo "twilio.env" >> .gitignore
source ./twilio.env

Windows

Temporarily set the environment variable (accessible only during the current CLI session):

set TWILIO_ACCOUNT_SID=YOUR_TWILIO_ACCOUNT_SID
set TWILIO_AUTH_TOKEN=YOUR_TWILIO_AUTH_TOKEN

Permanently set the environment variable (accessible in all subsequent CLI sessions):

setx TWILIO_ACCOUNT_SID "YOUR_TWILIO_ACCOUNT_SID"
setx TWILIO_AUTH_TOKEN "YOUR_TWILIO_AUTH_TOKEN"

3. Install the Twilio Helper Library

twilio-java uses Maven. At present the jars are available from a public maven repository.

Use the following dependency in your project to grab via Maven:

<dependency>
  <groupId>com.twilio.sdk</groupId>
  <artifactId>twilio</artifactId>
  <version>7.X.X</version>
  <scope>compile</scope>
</dependency>

or Gradle:

compile "com.twilio.sdk:twilio:7.X.X"

If you want to compile it yourself, here is how:

$ git clone [email protected]:twilio/twilio-java
$ cd twilio-java
$ mvn install       # Requires maven, download from http://maven.apache.org/download.html

Then, you can execute the following code.

String accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");
String authToken = Environment.GetEnvironmentVariable("TWILIO_AUTH_TOKEN");

Twilio.init(accountSid, authToken);

Message message = Message.creator(
    new PhoneNumber("+15558881234"),  // To number
    new PhoneNumber("+15559994321"),  // From number
    "Hello world!"                    // SMS body
).create();

System.out.println(message.getSid());

For more information, please visit the Twilio SMS Java documentation.