SendGrid Subuser Management: Multi-Account Email Administration

In this tutorial, you will learn about SendGrid Subuser Management: Multi. We cover key concepts, practical examples, and best practices to help you master this topic.

SendGrid subusers are child accounts under your parent account, each with its own API keys, sending reputation, IP pools, and usage limits — enabling multi-tenant email sending.

What You'll Learn

How to create and manage subusers, assign IP pools, enforce sending limits, monitor subuser activity, and isolate reputation between different email streams.

Why It Matters

Different email types (transactional, marketing, internal) should not share reputation. DodaTech uses subusers to separate alert emails (critical, monitored closely) from promotional emails (high volume, more bounce risk).

Real-World Use

Three subusers: "transactional" (welcome, receipts), "alerts" (security notifications), "marketing" (promotions). Each has its own IP pool and reputation. If marketing reputation drops, transactional email is unaffected.

flowchart LR
    A["Parent Account\ndodatech.com"] --> B["Subuser:\nTransactional"]
    A --> C["Subuser:\nAlerts"]
    A --> D["Subuser:\nMarketing"]
    B --> E["IP Pool\n10.0.0.1-3"]
    C --> F["IP Pool\n10.0.0.4-6"]
    D --> G["IP Pool\n10.0.0.7-9"]
    E --> H["99% Deliverability"]
    F --> H
    G --> I["95% Deliverability\n(isolated!)"]
    style A fill:#dbeafe,stroke:#2563eb
    style G fill:#fecaca,stroke:#dc2626
    style I fill:#fef3c7,stroke:#d97706

Creating Subusers

import requests
import os

API_KEY = os.environ["SENDGRID_ADMIN_API_KEY"]
BASE_URL = "https://api.sendgrid.com/v3"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

def create_subuser(username, email, password, ips, ip_pool):
    data = {
        "username": username,
        "email": email,
        "password": password,
        "ips": ips,
        "ip_pool": ip_pool
    }
    response = requests.post(
        f"{BASE_URL}/subusers",
        headers=HEADERS,
        json=data
    )
    subuser = response.json()
    print(f"Subuser created: {subuser['username']} (ID: {subuser['id']})")
    return subuser

transactional = create_subuser(
    "tx-dodatech", "tx-admin@dodatech.com", "SecurePass123!",
    ["168.1.1.1", "168.1.1.2"], "transactional-pool"
)
alerts = create_subuser(
    "alert-dodatech", "alerts@dodatech.com", "SecurePass456!",
    ["168.1.1.3", "168.1.1.4"], "alert-pool"
)
# Expected output: Subuser created: tx-dodatech (ID: 12345)

Managing Subuser Limits

def set_subuser_limits(username, max_emails_per_day):
    data = {
        "max_emails_per_day": max_emails_per_day
    }
    response = requests.patch(
        f"{BASE_URL}/subusers/{username}/limits",
        headers=HEADERS,
        json=data
    )
    print(f"Limits set for {username}: {max_emails_per_day}/day")

set_subuser_limits("tx-dodatech", 50000)
set_subuser_limits("alert-dodatech", 10000)
set_subuser_limits("mktg-dodatech", 200000)

# Get current usage
def get_subuser_stats(username):
    response = requests.get(
        f"{BASE_URL}/subusers/{username}/stats",
        headers=HEADERS,
        params={"limit": 7}
    )
    stats = response.json()
    print(f"Stats for {username}:")
    for day in stats:
        print(f"  {day['date']}: {day['stats'][0]['metrics']['delivered']} delivered")
    return stats

Monitoring Subuser Activity

def list_subusers():
    response = requests.get(f"{BASE_URL}/subusers", headers=HEADERS)
    subusers = response.json()

    print(f"{'Username':<20} {'IP Pool':<20} {'Emails Today':<15} {'Bounce %':<10}")
    print("-" * 65)

    for sub in subusers.get("result", []):
        username = sub["username"]
        ip_pool = sub.get("ip_pool", "N/A")
        # Get rep stats (simplified)
        stats_response = requests.get(
            f"{BASE_URL}/subusers/{username}/reputation",
            headers=HEADERS
        )
        rep = stats_response.json()
        emails_today = rep.get("emails_today", 0)
        bounce_pct = rep.get("bounce_percentage", 0)

        print(f"{username:<20} {ip_pool:<20} {emails_today:<15} {bounce_pct:.1f}%")

list_subusers()
# Expected output:
# Username             IP Pool              Emails Today    Bounce %
# -----------------------------------------------------------------
# tx-dodatech          transactional-pool   12340           0.5%
# alert-dodatech       alert-pool           2340            1.2%
# mktg-dodatech        marketing-pool       45670           4.8%

Subuser Authentication

# Each subuser has its own API key
# Apps use the subuser's API key for sending

# Subuser sends email with their own key:
sg_subuser = SendGridAPIClient("SG.subuser_api_key_here")
message = Mail(
    from_email="noreply@dodatech.com",
    to_emails="alice@example.com",
    subject="Transaction Receipt",
    html_content="<h1>Receipt</h1>"
)
response = sg_subuser.send(message)
print(f"Sent via subuser: {response.status_code}")

# Subusers cannot manage parent account settings
# Parent can impersonate subusers for management

Common Mistakes

1. Not Using Separate IP Pools

Without separate IP pools, all subusers share the same IPs. A marketing bounce spike affects transactional delivery.

2. Ignoring Subuser Reputation

Subuser reputation is independent. Monitor each subuser's bounce rate, spam reports, and delivery rate separately.

3. Setting Limits Too High

If a subuser's API key is compromised, high sending limits enable spam abuse. Start with low limits and increase as needed.

4. Forgetting to Provision IPs

Subusers need IPs assigned. Creating a subuser without IPs means they can't send. Add IPs during subuser creation or update them.

5. Not Monitoring Subuser Billing

Subuser usage is billed to the parent account. Set monthly spending limits (if available) or monitor subuser volume to prevent surprise bills.

Practice Questions

1. What is a subuser in SendGrid?
2. How do subusers help with reputation management?
3. How do you set sending limits per subuser?
4. How does authentication work for subusers?

Answers:

1. A subuser is a child account with its own API keys, IP pool, and sending reputation, managed under a parent account.
2. Subusers isolate reputation. If one subuser (marketing) develops a high bounce rate, other subusers (transactional) are unaffected because they use different IP pools.
3. Use PATCH /v3/subusers/{username}/limits to set max_emails_per_day and other limits.
4. Each subuser has its own API key. Apps authenticate as the subuser by using the subuser's API key. The parent admin can also impersonate subusers.

Challenge: Set up a multi-tenant email system: create 3 subusers (transactional, alerts, marketing) with separate IP pools, set appropriate sending limits per subuser, monitor reputation weekly, and implement alerts when bounce rate exceeds 3% for any subuser.

FAQ

Mini Project

Build a multi-tenant email infrastructure: create 3 subusers with separate IP pools and limits, configure domain authentication per subuser, monitor reputation per subuser, set up alerts for bounce rate thresholds, and implement an admin dashboard showing all subuser metrics.

What's Next

Email Deliverability — optimize sending practices for maximum inbox placement.