From 2f7c9eae5dfee949c584652c526dab346c152941 Mon Sep 17 00:00:00 2001
From: sburman <sburman@twilio.com>
Date: Mon, 20 Nov 2023 13:57:01 +0530
Subject: [PATCH] Add an example readme

---
 docs/use-cases/data-residency-set-hostname.md | 37 +++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 docs/use-cases/data-residency-set-hostname.md

diff --git a/docs/use-cases/data-residency-set-hostname.md b/docs/use-cases/data-residency-set-hostname.md
new file mode 100644
index 000000000..5b977d4eb
--- /dev/null
+++ b/docs/use-cases/data-residency-set-hostname.md
@@ -0,0 +1,37 @@
+# Choosing a hostname to send messages to
+
+Use the `setDataResidency` setter to specify which host to send to:
+
+Send to EU (hostname: `https://api.eu.sendgrid.com/`)
+```js
+const sgMail = require('@sendgrid/mail');
+sgMail.setDataResidency('eu');
+const msg = {
+  to: 'recipient@example.org',
+  from: 'sender@example.org',
+  subject: 'Hello world',
+  text: 'Hello plain world!',
+  html: '<p>Hello HTML world!</p>',
+};
+sgMail.send(msg);
+```
+Send to Global region, this is also the default host, if the setter is not used
+(hostname: `https://api.sendgrid.com/`)
+```js
+const sgMail = require('@sendgrid/mail');
+sgMail.setDataResidency('global');
+const msg = {
+  to: 'recipient@example.org',
+  from: 'sender@example.org',
+  subject: 'Hello world',
+  text: 'Hello plain world!',
+  html: '<p>Hello HTML world!</p>',
+};
+sgMail.send(msg);
+```
+
+## Limitations
+
+1. Emails can only be sent to two hosts for now; 'eu' (https://api.eu.sendgrid.com/) and 'global' (https://api.eu.sendgrid.com/)
+2. The default hostname is https://api.sendgrid.com/
+3. The valid values for `region` in `client.setDataResidency(region)` are only `eu` and `global`. Case-sensitive.