How to Create a EU Regional Subuser with the Twilio SendGrid API

For more information about Subusers, visit the longform Subusers documentation. You can also manage Subusers in the SendGrid console.

This guide provides a step-by-step process to create a regional subuser using the Twilio SendGrid API for the European Union (EU) region. By the end of this guide, you will be able to set up a subuser, configure the necessary settings, and send emails from the EU region.

Before you begin, ensure you have the following:

• A Twilio SendGrid API account on the Pro plan (or above) with a dedicated IP. If you don't have an account, you can sign up here.
• An API key for your parent account with the necessary permissions.

Create a subuser bound to the EU region. When creating the subuser, specify the region as eu.

1
curl -X POST "https://api.sendgrid.com/v3/subusers" \
2
--header "Authorization: Bearer $YOUR_API_KEY" \
3
--header "Content-Type: application/json" \
4
--data '{
5
  "username": "john@example.com",
6
  "email": "john@example.com",
7
  "password": "johns_password",
8
  "region": "eu",
9
  "include_region": true
10
}'

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 parent account and the subuser.

1
curl -X POST "https://api.sendgrid.com/v3/send_ips/ips" \
2
--header "Authorization: Bearer $YOUR_API_KEY" \
3
--header "Content-Type: application/json" \
4
--data '{
5
  "is_auto_warmup": false,
6
  "is_parent_assigned": true,
7
  "subusers": ["SUBUSER_ID"],
8
  "region": "eu",
9
  "include_region": true
10
}'

Note:

• Replace YOUR_API_KEY with your parent account's API key.
• Replace SUBUSER_ID with the ID of the subuser you created in Step 1. You can retrieve the subuser ID by listing your subusers using the API.

Configure Domain Authentication by adding the required records to your DNS host. Follow these steps to complete Domain Authentication:

1. Authenticate your domain

   Copy code block

   1
   curl -X POST "https://api.sendgrid.com/v3/whitelabel/domains" \
   2
   --header "Authorization: Bearer YOUR_API_KEY" \
   3
   --header "Content-Type: application/json" \
   4
   --data '{
   5
     "domain": "example.com",
   6
     "region": "eu"
   7
   }'

   Note: Replace YOUR_API_KEY with your parent account's API key and example.com with your sending domain.

2. Validate the domain authentication

   Copy code block

   1
   curl -X POST "https://api.sendgrid.com/v3/whitelabel/domains/{DOMAIN_ID}/validate" \
   2
   --header "Authorization: Bearer YOUR_API_KEY"

   Note: Replace {DOMAIN_ID} with the domain ID returned from the previous step.

3. Associate the authenticated domain with your EU-based subuser

   Copy code block

   1
   curl -X POST "https://api.sendgrid.com/v3/whitelabel/domains/{DOMAIN_ID}/subuser" \
   2
   --header "Authorization: Bearer $YOUR_API_KEY" \
   3
   --header "Content-Type: application/json" \
   4
   --data '{"username": "john@example.com"}'

   Note: Replace YOUR_API_KEY with your parent account's API key, {DOMAIN_ID} with your domain ID, and john@example.com with the subuser's username.

Create an API key for your EU-based subuser via the SendGrid Console or the API. This key should have the mail.send permission.

Using the API:

Authenticate as the subuser when creating the API key.

1
curl -X POST "https://api.sendgrid.com/v3/api_keys" \
2
--header "Authorization: Bearer $SUBUSER_API_KEY" \
3
--header "Content-Type: application/json" \
4
--data '{
5
  "name": "MyEU API Key",
6
  "scopes": ["mail.send"]
7
}'

Note: Replace SUBUSER_API_KEY with the API key of the subuser john@example.com.

Now that you have an API key for your EU subuser, you can use that subuser to send emails. Make sure to send emails using the base URL https://api.eu.sendgrid.com.

1
curl -X POST "https://api.eu.sendgrid.com/v3/mail/send" \
2
--header "Authorization: Bearer $SUBUSER_API_KEY" \
3
--header "Content-Type: application/json" \
4
--data '{
5
  "personalizations": [
6
    {
7
      "to": [
8
        {
9
          "email": "recipient@example.com"
10
        }
11
      ]
12
    }
13
  ],
14
  "from": {
15
    "email": "sender@example.com"
16
  },
17
  "subject": "Hello, World!",
18
  "content": [
19
    {
20
      "type": "text/plain",
21
      "value": "Heya!"
22
    }
23
  ]
24
}'

Note: Replace SUBUSER_API_KEY with the API key you created for the subuser. Update recipient@example.com and sender@example.com with the appropriate email addresses.

By following these steps, you have successfully created a regional subuser in the EU, configured the necessary settings, and sent an email. This setup helps in complying with data residency requirements by ensuring that data does not leave the EU region.

For more detailed information, refer to the original blog post: Setup a Subuser and IP Address in the EU.

• Data Retention and Deletion in Twilio Products
• European Commission adopts new adequacy decision for safe and trusted EU-US data flows
• EU-US Data Privacy Framework
• Erase Recipients' Email Data | Twilio