Skip to content

Commit 0164ff8

Browse files
author
Matt Bernier
authored
Merge pull request sendgrid#597 from shriyash/master
Adds file structure for use cases sendgrid#596
2 parents 8a939e2 + 07ce7cb commit 0164ff8

18 files changed

+443
-0
lines changed

use-cases/README.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
This documentation provides examples for specific SendGrid v3 API use cases. Please [open an issue](https://github.com/sendgrid/sendgrid-nodejs/issues) or make a pull request for any email use cases you would like us to document here. Thank you!
2+
3+
# Email Use Cases
4+
* [Send a Single Email to a Single Recipient](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/single-email-single-recipient.md)
5+
* [Send a Single Email to Multiple Recipients](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/single-email-multiple-recipients.md)
6+
* [Send Multiple Emails to Multiple Recipients](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/multiple-emails-multiple-recipients.md)
7+
* [CC, BCC and Reply To](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/cc-bcc-reply-to.md)
8+
* [Flexible Email Address Fields](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/flexible-address-fields.md)
9+
* [Handling Success/Failure/Errors](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/success-failure-errors.md)
10+
* [Advanced Usage](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/advanced.md)
11+
* [Transactional Templates](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/transactional-templates.md)
12+
* [Attachments](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/attachments.md)
13+
* [Customization Per Recipient](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/customization.md)
14+
* [Manually Providing Content](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/manual-content.md)
15+
* [Specifying Time to Send At](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/time-to-send.md)
16+
* [Specifying Custom Headers](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/custom-headers.md)
17+
* [Specifying Categories](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/categories.md)
18+
* [Kitchen Sink - an example with all settings used](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/kitchen-sink.md)
19+
20+
# Non-mail Use Cases
21+
* [How to Setup a Domain Whitelabel](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/domain-white-label.md)
22+
* [How to View Email Statistics](https://github.com/sendgrid/sendgrid-nodejs/blob/master/use-cases/email-stats.md)

use-cases/advanced.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Advanced Usage
2+
3+
All other advanced settings are supported and can be passed in through the msg object according to the expected format as per the [API v3 documentation](https://sendgrid.com/docs/API_Reference/api_v3.html). Note that you can use either `camelCase` or `snake_case` for property names.

use-cases/attachments.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Attachments
2+
3+
Attachments can be sent by providing an array of `attachments` as per the [API specification](https://sendgrid.com/docs/API_Reference/api_v3.html):
4+
5+
```js
6+
const sgMail = require('@sendgrid/mail');
7+
sgMail.setApiKey(process.env.SENDGRID_API_KEY);
8+
const msg = {
9+
to: 'recipient@example.org',
10+
from: 'sender@example.org',
11+
subject: 'Hello attachment',
12+
html: '<p>Here’s an attachment for you!</p>',
13+
attachments: [
14+
{
15+
content: 'Some base 64 encoded attachment content',
16+
filename: 'some-attachment.txt',
17+
type: 'plain/text',
18+
disposition: 'attachment',
19+
contentId: 'mytext'
20+
},
21+
],
22+
};
23+
```

use-cases/categories.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Specifying Categories
2+
3+
Use the `categories` property to provide an array of categories for your email:
4+
5+
```js
6+
const msg = {
7+
to: 'recipient@example.org',
8+
from: 'sender@example.org',
9+
subject: 'Hello email with categories',
10+
html: '<p>Some email content</p>',
11+
categories: [
12+
'transactional', 'customer', 'weekly',
13+
],
14+
};
15+
```
16+
17+
Specifying a single `category` is also supported:
18+
19+
```js
20+
const msg = {
21+
to: 'recipient@example.org',
22+
from: 'sender@example.org',
23+
subject: 'Hello email with categories',
24+
html: '<p>Some email content</p>',
25+
category: 'transactional',
26+
};
27+
```

use-cases/cc-bcc-reply-to.md

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# CC, BCC and Reply To
2+
3+
You can specify the `cc`, `bcc` and `replyTo` fields for more control over who you send the email to and where people will reply to:
4+
5+
```js
6+
const msg = {
7+
to: 'recipient@example.org',
8+
cc: 'someone@example.org',
9+
bcc: ['me@example.org', 'you@example.org'],
10+
from: 'sender@example.org',
11+
replyTo: 'othersender@example.org',
12+
subject: 'Hello world',
13+
text: 'Hello plain world!',
14+
html: '<p>Hello HTML world!</p>',
15+
};
16+
```

use-cases/custom-headers.md

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Specifying Custom Headers
2+
3+
Use the `headers` property to specify any custom headers (note that these can also be set globally per the [API specification](https://sendgrid.com/docs/API_Reference/api_v3.html):
4+
5+
```js
6+
const msg = {
7+
to: 'recipient@example.org',
8+
from: 'sender@example.org',
9+
subject: 'Hello custom header',
10+
html: '<p>Some email content</p>',
11+
headers: {
12+
'X-CustomHeader': 'Custom header value',
13+
},
14+
};
15+
```

use-cases/customization.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Customization Per Recipient
2+
3+
To send multiple individual emails to multiple recipients with additional customization (like a different subject), use the `personalizations` field as per the [API definition](https://sendgrid.com/docs/API_Reference/api_v3.html) instead of `to`, leveraging all customization options:
4+
5+
```js
6+
const msg = {
7+
personalizations: [
8+
{
9+
to: 'recipient1@example.org',
10+
subject: 'Hello recipient 1',
11+
substitutions: {
12+
name: 'Recipient 1',
13+
id: '123',
14+
},
15+
headers: {
16+
'X-Custom-Header': 'Recipient 1',
17+
},
18+
customArgs: {
19+
myArg: 'Recipient 1',
20+
},
21+
},
22+
{
23+
to: 'recipient2@example.org',
24+
subject: 'Hello recipient 2',
25+
substitutions: {
26+
name: 'Recipient 2',
27+
id: '456',
28+
},
29+
headers: {
30+
'X-Custom-Header': 'Recipient 2',
31+
},
32+
customArgs: {
33+
myArg: 'Recipient 1',
34+
},
35+
sendAt: 1500077141,
36+
}
37+
],
38+
from: 'sender@example.org',
39+
text: 'Hello plain world!',
40+
html: '<p>Hello HTML world!</p>',
41+
};
42+
```
43+
44+
If the `substitutions` field is provided globally as well, these substitutions will be merged with any custom substitutions you provide in the `personalizations`.

use-cases/domain-white-label.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# How to Setup a Domain Whitelabel
2+
3+
You can find documentation for how to setup a domain whitelabel via the UI [here](https://sendgrid.com/docs/Classroom/Basics/Whitelabel/setup_domain_whitelabel.html) and via API [here](https://github.com/sendgrid/sendgrid-nodejs/blob/master/packages/client/USAGE.md#whitelabel).
4+
5+
Find more information about all of SendGrid's whitelabeling related documentation [here](https://sendgrid.com/docs/Classroom/Basics/Whitelabel/index.html).

use-cases/email-stats.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# How to View Email Statistics
2+
3+
You can find documentation for how to view your email statistics via the UI [here](https://app.sendgrid.com/statistics) and via API [here](https://github.com/sendgrid/sendgrid-nodejs/blob/master/packages/client/USAGE.md#stats).
4+
5+
Alternatively, we can post events to a URL of your choice via our [Event Webhook](https://sendgrid.com/docs/API_Reference/Webhooks/event.html) about events that occur as SendGrid processes your email.

use-cases/flexible-address-fields.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
## Flexible email address fields
2+
The email address fields (`to`, `from`, `cc`, `bcc`, `replyTo`) are flexible and can be any of the following:
3+
4+
```js
5+
const msg = {
6+
7+
//Simple email address string
8+
to: 'someone@example.org',
9+
10+
//Email address with name
11+
to: 'Some One <someone@example.org>',
12+
13+
//Object with name/email
14+
to: {
15+
name: 'Some One',
16+
email: 'someone@example.org',
17+
},
18+
19+
//Arrays are supported for to, cc and bcc
20+
to: [
21+
'someone@example.org',
22+
'Some One <someone@example.org>',
23+
{
24+
name: 'Some One',
25+
email: 'someone@example.org',
26+
},
27+
],
28+
};
29+
```

0 commit comments

Comments
 (0)