Subusers API
For more information about Subusers, visit the longform Subusers documentation. You can also manage Subusers in the SendGrid console.
How to Create a EU Regional Subuser with the Twilio SendGrid API
This guide provides a step-by-step process on how to create a regional subuser using the Twilio SendGrid API, specifically for the European Union (EU) region. By following this guide, you will be able to set up a subuser, configure necessary settings, and send emails from the EU region.
Prerequisites
Before you begin, ensure you have the following:
- A Twilio SendGrid API account on the Pro plan or above with a dedicated IP. Sign up here
- An API key for your parent account
- Rename $YOUR_API_KEY in the examples below with the name of your environment variable
Steps to Create a EU Regional Subuser
Step 1: Create a Subuser
Create a subuser that is bound to the EU region. When creating the subuser, specify the region as eu
.
curl -X POST "https://api.sendgrid.com/v3/subusers" \
--header "Authorization: Bearer $YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{"username":"John@example.com","email":"John@example.com","password":"johns_password","region":"eu","include_region":true}'
Step 2: Add a Regional IP and Assign to Parent Account and Subusers
You can add one IP address per month via self-service. The following command adds an EU-based IP address and assigns it to the subuser and parent accounts.
curl -H "Authorization: Bearer $YOUR_API_KEY" -X POST \
'https://api.sendgrid.com/v3/send_ips/ips' -d '{"is_auto_warmup":false, "is_parent_assigned":true, "subusers":["12345678"], "region":"eu", "include_region":true}'
Step 3: Complete Sender Authentication
Configure Domain Authentication by adding a record to your DNS host. Follow these steps to complete Domain Authentication:
- Authenticate your domain
curl -X POST "https://api.sendgrid.com/v3/whitelabel/domains" \
--header "Authorization: Bearer $YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{"domain": "example.com", "region": "eu"}'
- Validate the domain authentication
curl -X POST "https://api.sendgrid.com/v3/whitelabel/domains/{DOMAIN_ID}/validate" \
--header "Authorization: Bearer $YOUR_API_KEY"
- Associate the authenticated domain with your EU-based subuser
curl -X POST "https://api.sendgrid.com/v3/whitelabel/domains/{DOMAIN_ID}/subuser" \
--header "Authorization: Bearer $YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{"username":"jdoe"}'
Step 4: Create a Twilio SendGrid API Key to Send Emails
Create an API key for your EU-based subuser via the Twilio SendGrid Console or the API. This key should have the mail.send
permission.
curl -X POST "https://api.sendgrid.com/v3/api_keys" \
--header "Authorization: Bearer $YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data '{"name":"MyEU API Key", "scopes":["mail.send","alerts.create","alerts.read"]}'
Step 5: Send Your Email
Now that you have an API Key for your EU subuser, you can use that subuser to send email. Make sure to send email using the base URL api.eu.sendgrid.com
.
curl --request POST --url https://api.eu.sendgrid.com/v3/mail/send --header 'Authorization: Bearer $YOUR_API_KEY' --header 'Content-Type: application/json' --data '{"personalizations":[{"to":[{"email":"recipient@example.com"}]}],"from":{"email":"sender@example.com"},"subject":"Hello, World!","content":[{"type":"text/plain","value":"Heya!"}]}'
Conclusion
By following these steps, you have successfully created a regional subuser in the EU, configured necessary settings, and sent an email. This setup helps in complying with data residency requirements by ensuring that the data does not leave the EU region.
For more detailed information, refer to the original blog post: Regional Email Public Beta: Set Up a Subuser and IP Address in the EU.
Additional Resources
Need some help?
We all do sometimes. Get help now from the Twilio SendGrid Support Team.
Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.