SendGrid API Overview, from SendGrid Deliever Nov 8 2012

1. API Workshop
#SGDelivered

2. Hi, I’m Brandon.
@brandonmwest
brandon.west@sendgrid.com
#SGDelivered

3. What is SendGrid?
#SGDelivered

4. What is SendGrid?
• Cloud-based SMTP provider
#SGDelivered

5. What is SendGrid?
• Cloud-based SMTP provider
• Massively scalable
#SGDelivered

6. What is SendGrid?
• Cloud-based SMTP provider
• Massively scalable
• Analytics on emails you send
#SGDelivered

7. What is SendGrid?
• Cloud-based SMTP provider
• Massively scalable
• Analytics on emails you send
• Robust APIs for developers to integrate
#SGDelivered

9. If you learn 1 thing...
SendGrid > Email
Relay
#SGDelivered

10. APIs Overview
Q: Why should I care about the SendGrid APIs?
#SGDelivered

11. APIs Overview
Q: Why should I care about the SendGrid APIs?
A: There are a lot of reasons, but the
#SGDelivered

12. APIs Overview
Q: Why should I care about the SendGrid APIs?
A: There are a lot of reasons, but the
• Reduce code complexity
#SGDelivered

13. APIs Overview
Q: Why should I care about the SendGrid APIs?
A: There are a lot of reasons, but the
• Reduce code complexity
• Deeper analytics & tracking
#SGDelivered

14. APIs Overview
Q: Why should I care about the SendGrid APIs?
A: There are a lot of reasons, but the
• Reduce code complexity
• Deeper analytics & tracking
• Less resource consumption
#SGDelivered

15. APIs Overview
Q: Why should I care about the SendGrid APIs?
A: There are a lot of reasons, but the
• Reduce code complexity
• Deeper analytics & tracking
• Less resource consumption
• Better UX
#SGDelivered

16. Why Use SendGrid?
Time is valuable.
Especially developer time.
#SGDelivered

17. APIs Overview
What APIs does SendGrid Offer?
API
#SGDelivered

18. APIs Overview
What APIs does SendGrid Offer?
• SMTP API
API
#SGDelivered

19. APIs Overview
What APIs does SendGrid Offer?
• SMTP API
• Web API
API
#SGDelivered

20. APIs Overview
What APIs does SendGrid Offer?
• SMTP API
• Web API
• Newsletter API
API
#SGDelivered

21. APIs Overview
What APIs does SendGrid Offer?
• SMTP API
• Web API
• Newsletter API
• Reseller API
API
#SGDelivered

22. APIs Overview
What APIs does SendGrid Offer?
• SMTP API • Subuser API
• Web API
• Newsletter API
• Reseller API
API
#SGDelivered

23. APIs Overview
What APIs does SendGrid Offer?
• SMTP API • Subuser API
• Web API • Credentials API
• Newsletter API
• Reseller API
API
#SGDelivered

24. APIs Overview
What APIs does SendGrid Offer?
• SMTP API • Subuser API
• Web API • Credentials API
• Newsletter API • Event Webhook
• Reseller API
API
#SGDelivered

25. APIs Overview
What APIs does SendGrid Offer?
• SMTP API • Subuser API
• Web API • Credentials API
• Newsletter API • Event Webhook
• Reseller API • Inbound Parse Webhook
API
#SGDelivered

26. SMTP API
Custom SMTP header that contains instructions on
how to process your email
X-SMTPAPI: { ... }
Add extra information, filters, & manipulations:
#SGDelivered

27. SMTP API
Custom SMTP header that contains instructions on
how to process your email
X-SMTPAPI: { ... }
Add extra information, filters, & manipulations:
• Define multiple recipients
#SGDelivered

28. SMTP API
Custom SMTP header that contains instructions on
how to process your email
X-SMTPAPI: { ... }
Add extra information, filters, & manipulations:
• Define multiple recipients
• Text Substitutions
#SGDelivered

29. SMTP API
Custom SMTP header that contains instructions on
how to process your email
X-SMTPAPI: { ... }
Add extra information, filters, & manipulations:
• Define multiple recipients
• Text Substitutions
• Categories
#SGDelivered

30. SMTP API
Custom SMTP header that contains instructions on
how to process your email
X-SMTPAPI: { ... }
Add extra information, filters, & manipulations:
• Define multiple recipients
• Text Substitutions
• Categories
• Unique arguments / Identifiers
#SGDelivered

31. SMTP API
Example: Billing notification
X-SMTPAPI: {
"to": ["brandon.west@sendgrid.com"],
"category": "billing_notifications",
"unique_args": {
"user_id": "12345"
},
"sub": {
"%amount%": ["$9.95"]
}
}
#SGDelivered

32. SMTP API
Example: Billing notification (cont)
#SGDelivered

33. Metadata from Rails
# Set headers for SendGrid.
def add_sendgrid_headers(action, args)
mailer = self.class.name
args = Hash[ method(action).parameters.map(&:last).zip(args) ]
headers "X-SMTPAPI" => {
category: [ mailer, "#{mailer}##{action}" ],
unique_args: { environment: Rails.env, arguments: args.inspect }
}.to_json
end
#SGDelivered

34. Metadata from Rails
class ApplicationMailer < ActionMailer::Base
# Call add_sendgrid_headers after generating each mail.
def initialize(method_name=nil, *args)
super.tap do
add_sendgrid_headers(method_name, args) if method_name
end
end
private
# Set headers for SendGrid.
def add_sendgrid_headers(action, args)
mailer = self.class.name
args = Hash[ method(action).parameters.map(&:last).zip(args) ]
headers "X-SMTPAPI" => {
category: [ mailer, "#{mailer}##{action}" ],
unique_args: { environment: Rails.env, arguments: args.inspect }
}.to_json
end
end
#SGDelivered

35. Rails Metadata
#SGDelivered

36. Customer Highlight
qup.tv
Queue, rate, or watch movies on Netflix instant with
one click!
#SGDelivered

37. Web API
Send mail or manipulate SendGrid settings
via HTTP
Anything (almost) you can do from the
#SGDelivered

38. Web API
Send mail or manipulate SendGrid settings
via HTTP
Anything (almost) you can do from the
• Edit profile / account information
#SGDelivered

39. Web API
Send mail or manipulate SendGrid settings
via HTTP
Anything (almost) you can do from the
• Edit profile / account information
• Add new Incoming Parse endpoints
#SGDelivered

40. Web API
Send mail or manipulate SendGrid settings
via HTTP
Anything (almost) you can do from the
• Edit profile / account information
• Add new Incoming Parse endpoints
• Retrieve stats
#SGDelivered

41. Web API
Send mail or manipulate SendGrid settings
via HTTP
Anything (almost) you can do from the
• Edit profile / account information
• Add new Incoming Parse endpoints
• Retrieve stats
• Manage lists (Bounces, Blocks, Unsubscribes, etc.)
#SGDelivered

42. Web API
Send mail or manipulate SendGrid settings
via HTTP
Anything (almost) you can do from the
• Edit profile / account information
• Add new Incoming Parse endpoints
• Retrieve stats
• Manage lists (Bounces, Blocks, Unsubscribes, etc.)
• Add / Remove filters (apps)
#SGDelivered

43. Web API
Web API endpoints have the following
https://sendgrid.com/api/<MODULE>.<ACTION>.<FORMAT>
#SGDelivered

44. Web API
Web API endpoints have the following
https://sendgrid.com/api/<MODULE>.<ACTION>.<FORMAT>
Example: Send Email over HTTP
#SGDelivered

45. Web API
Web API endpoints have the following
https://sendgrid.com/api/<MODULE>.<ACTION>.<FORMAT>
Example: Send Email over HTTP
curl -X POST http://sendgrid.com/api/mail.send.json
-d “to=john@example.com”
-d “from=hello@myapp.com”
-d “subject=hello world email”
-d “text=some body text”
-d “api_user=your_sendgrid_username”
-d “api_key=your_sendgrid_key”
#SGDelivered

46. Web API vs. SMTP
Q: Why would I use HTTP instead of SMTP?
(Don’t worry, this is a really common question)
#SGDelivered

47. Web API vs. SMTP
Q: Why would I use HTTP instead of SMTP?
(Don’t worry, this is a really common question)
A: Normally, you won’t have to. Unless...
#SGDelivered

48. Web API vs. SMTP
Q: Why would I use HTTP instead of SMTP?
(Don’t worry, this is a really common question)
A: Normally, you won’t have to. Unless...
• Your ISP is blocking common SMTP ports
#SGDelivered

49. Web API vs. SMTP
Q: Why would I use HTTP instead of SMTP?
(Don’t worry, this is a really common question)
A: Normally, you won’t have to. Unless...
• Your ISP is blocking common SMTP ports
• There is high latency between your app and
SendGrid
#SGDelivered

50. Web API vs. SMTP
Q: Why would I use HTTP instead of SMTP?
(Don’t worry, this is a really common question)
A: Normally, you won’t have to. Unless...
• Your ISP is blocking common SMTP ports
• There is high latency between your app and
SendGrid
• Difficult to install / configure SMTP drivers
#SGDelivered

51. Web API vs. SMTP
Q: Why would I use HTTP instead of SMTP?
(Don’t worry, this is a really common question)
A: Normally, you won’t have to. Unless...
• Your ISP is blocking common SMTP ports
• There is high latency between your app and
SendGrid
• Difficult to install / configure SMTP drivers
• Simplicity for developers
#SGDelivered

52. Newsletter API
Access the SendGrid newsletter app via the
API
https://sendgrid.com/api/newsletter/<ACTION>.<FORMAT>
• Newsletter content
• Recipient lists
• Sender identities
• Scheduled deliveries
#SGDelivered

53. Webhooks
Q: What are Webhooks?
WEB
HOOK
#SGDelivered

54. Webhooks
Q: What are Webhooks?
A: Webhooks are like inverse API calls;
you tell us where the data needs to go,
we send it there.
WEB
HOOK
#SGDelivered

55. Event Notification
Receive notifications when SendGrid events happen
HTTP POST
(like a form submit)
#SGDelivered

56. Event Notification
Receive notifications when SendGrid events happen
HTTP POST
(like a form submit)
•Processed •Opened
•Dropped •Clicked
•Delivered •Spam Reported
•Bounced •Unsubscribed
#SGDelivered

57. Event Notification
What does an event notification look like?
{
"email":"john@example.com",
"timestamp": 1322000095,
"unique_arg":"some argument",
"event":"delivered"
}
#SGDelivered

58. Event Notification
Q: Why would I want to use the event
A: Use it to enhance your existing email
functionality and gain smart customer
insight. reactive API)
(It’s a very
#SGDelivered

59. Inbound Parse
Lets you receive email in your application
EMAIL POST
#SGDelivered

60. Inbound Parse
Lets you receive email in your application
EMAIL POST
1. User sends email to *@yourapplication.com
2. SendGrid parses email & attachments
3. SendGrid POSTs the email to your application
#SGDelivered

61. Customer Highlight
thebirdy.com
Answer one email a day, and track what you spend.
Create categories by tagging your purchases like
#twitter. Super simple.
#SGDelivered

62. Inbound Parse
1. Configure your hostname and URL settings
http://sendgrid.com/developer/reply
2. Point your domain’s MX records at SendGrid
Type Value
MX 0 mx.sendgrid.net
3. Return a 200 status code from your application
#SGDelivered

63. Additional APIs
#SGDelivered

64. Additional APIs
Subuser API
#SGDelivered

65. Additional APIs
Subuser API
• Manage and control subuser accounts
#SGDelivered

66. Additional APIs
Subuser API
• Manage and control subuser accounts
Reseller API
#SGDelivered

67. Additional APIs
Subuser API
• Manage and control subuser accounts
Reseller API
• For partners who want to integrate their platform with
SendGrid
#SGDelivered

68. Additional APIs
Subuser API
• Manage and control subuser accounts
Reseller API
• For partners who want to integrate their platform with
SendGrid
Multiple Credentials API
#SGDelivered

69. Additional APIs
Subuser API
• Manage and control subuser accounts
Reseller API
• For partners who want to integrate their platform with
SendGrid
Multiple Credentials API
• Add new API keys and users to your account
#SGDelivered

70. Demo Time!
http://github.com/theycallmeswift
#SGDelivered

71. Questions?
#SGDelivered

72. Resources
• Documentation/API Workshop:
http://docs.sendgrid.com/
• Official Libraries: https://github.com/
sendgrid/
• Support: http://support.sendgrid.com/
#SGDelivered

73. Thanks!
@brandonmwest
brandon.west@sendgrid.com
#SGDelivered