Subuser & Domain Management

👥 Subuser Management

Overview

Each DashClicks account gets its own Sendgrid subuser for reputation isolation. This ensures that one account's email practices don't affect another's sending reputation.

Subuser Architecture Benefits:

• 📧 Independent email quotas per account
• 📊 Isolated reputation scores
• 🔒 Separate authentication credentials
• 🌐 Individual domain assignments
• 📈 Per-account analytics

🔗 API Endpoints

Subuser Operations

Endpoint	Method	Scope	Description
/v1/integrations/sendgrid/subusers	POST	communications	Create new subuser
/v1/integrations/sendgrid/subusers/:id	PUT	communications	Enable/disable subuser
/v1/integrations/sendgrid/subusers/:id	DELETE	communications	Delete subuser
/v1/integrations/sendgrid/subusers/:id/reputation	GET	communications	Get subuser reputation score

Domain Operations

Endpoint	Method	Scope	Description
/v1/integrations/sendgrid/subusers/domains	POST	accounts.email_custom_domain, accounts	Add domain to subuser
/v1/integrations/sendgrid/subusers/domains/:domain_id	DELETE	accounts.email_custom_domain, accounts	Delete subuser domain
/v1/integrations/sendgrid/subusers/domains/:domain_id/validate	POST	accounts.email_custom_domain, accounts	Validate domain DNS

👤 Subuser API Reference

Create Subuser

Endpoint: POST /v1/integrations/sendgrid/subusers

Purpose: Create new Sendgrid subuser for a DashClicks account

Request Body:

{
  "username": "dashclicks_acc_507f191e",
  "email": "subuser@dashclicks.com"
}

Validation:

• username: Required string
• email: Required email format

Process:

1. Generate Password: Random 10 characters + "1D" suffix

   const password = Math.random().toString(36).substring(2, 12) + '1D';

2. Get Available IP: Query Sendgrid for available IP addresses

   GET https://api.sendgrid.com/v3/ips
   Authorization: Bearer {SENDGRID_API_KEY}

3. Check Existing: Verify subuser doesn't already exist in database

4. Create Subuser: Call Sendgrid API

   POST https://api.sendgrid.com/v3/subusers
   Authorization: Bearer {SENDGRID_API_KEY}
   Content-Type: application/json
   
   {
     "username": "dashclicks_acc_507f191e",
     "email": "subuser@dashclicks.com",
     "password": "random12341D",
     "ips": ["192.168.1.1"]
   }

5. Assign Default Domain: Add default domain to subuser

   PUT https://api.sendgrid.com/v3/whitelabel/domains/{SENDGRID_DEFAULT_DOMAIN_ID}/subuser
   Authorization: Bearer {SENDGRID_API_KEY}
   
   {
     "username": "dashclicks_acc_507f191e"
   }

6. Store in Database: Save to account document

   await SubUserCollection.addSubUserDoc({
     account_id: account_id,
     sendgrid: {
       subuser: {
         username: 'dashclicks_acc_507f191e',
         user_id: 123456,
         email: 'subuser@dashclicks.com',
         disabled: false,
       },
       domain_assigned: true,
       domains: [],
     },
   });

Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "username": "dashclicks_acc_507f191e",
    "user_id": 123456,
    "email": "subuser@dashclicks.com",
    "disabled": false
  }
}

Error Scenarios:

// Subuser already exists
{
  "success": false,
  "errno": 400,
  "message": "Subuser already exists for this account"
}

// No available IPs
{
  "success": false,
  "errno": 500,
  "message": "No available IP addresses"
}

Update Subuser (Enable/Disable)

Endpoint: PUT /v1/integrations/sendgrid/subusers/:id

Purpose: Enable or disable subuser account

Path Parameters:

• id (required) - DashClicks account ID

Request Body:

{
  "disabled": true
}

Sendgrid API:

PATCH https://api.sendgrid.com/v3/subusers/{username}
Authorization: Bearer {SENDGRID_API_KEY}
Content-Type: application/json

{
  "disabled": true
}

Database Update:

await SubUserCollection.updateSubUserStatusDoc(account_id, disabled);

Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "username": "dashclicks_acc_507f191e",
    "user_id": 123456,
    "disabled": true
  }
}

Use Cases:

• Temporarily suspend email sending for an account
• Re-enable after suspension period
• Troubleshooting delivery issues

Delete Subuser

Endpoint: DELETE /v1/integrations/sendgrid/subusers/:id

Purpose: Permanently delete subuser and all associated data

Path Parameters:

• id (required) - DashClicks account ID

Process:

1. Get subuser username from database
2. Delete via Sendgrid API:

   DELETE https://api.sendgrid.com/v3/subusers/{username}
   Authorization: Bearer {SENDGRID_API_KEY}

3. Delete from database:

   await SubUserCollection.deleteSubUserDoc(account_id);

Response:

{
  "success": true,
  "message": "Subuser deleted successfully"
}

Warning: This action is irreversible. All subuser data, including:

• API keys
• Domain configurations
• Email statistics
• Reputation history

will be permanently deleted.

Get Subuser Reputation

Endpoint: GET /v1/integrations/sendgrid/subusers/:id/reputation

Purpose: Retrieve sender reputation score (0-100)

Path Parameters:

• id (required) - DashClicks account ID

Sendgrid API:

GET https://api.sendgrid.com/v3/subusers/reputations?usernames={username}
Authorization: Bearer {SENDGRID_API_KEY}

Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": [
    {
      "username": "dashclicks_acc_507f191e",
      "reputation": 99.8
    }
  ]
}

Reputation Score Interpretation:

• 95-100: Excellent - high deliverability
• 80-94: Good - acceptable deliverability
• 70-79: Fair - may experience issues
• Below 70: Poor - high bounce/spam rates

🌐 Domain Management

Overview

Custom domains improve email deliverability and branding by allowing emails to be sent from your own domain (e.g., @yourdomain.com) instead of Sendgrid's shared domains.

Domain Authentication Benefits:

• ✉️ Better deliverability rates
• 🔒 Enhanced security (SPF, DKIM, DMARC)
• 🎨 Branded sender addresses
• 📊 Improved sender reputation
• 🛡️ Reduced spam complaints

Add Domain to Subuser

Endpoint: POST /v1/integrations/sendgrid/subusers/domains

Purpose: Add custom domain to subuser for authenticated sending

Request Body:

{
  "domain": "dashclicks.com",
  "subdomain": "mail"
}

Validation:

• domain: Required string (valid domain format)
• subdomain: Required string (subdomain prefix)

Sendgrid API:

POST https://api.sendgrid.com/v3/whitelabel/domains
Authorization: Bearer {SENDGRID_API_KEY}
On-Behalf-Of: {subuser_username}
Content-Type: application/json

{
  "domain": "dashclicks.com",
  "subdomain": "mail",
  "automatic_security": false
}

Process:

1. Get subuser from account document
2. Create domain via Sendgrid API (on-behalf-of subuser)
3. Auto-add DMARC record:

   {
     type: 'txt',
     host: '_dmarc.dashclicks.com',
     data: 'v=DMARC1;p=none',
     valid: false
   }

4. Push to account.sendgrid.domains array in database

Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": [
    {
      "id": 12345678,
      "domain": "dashclicks.com",
      "subdomain": "mail",
      "valid": false,
      "dns": {
        "mail_cname": {
          "host": "mail.dashclicks.com",
          "type": "CNAME",
          "data": "u12345678.wl.sendgrid.net",
          "valid": false
        },
        "dkim1": {
          "host": "s1._domainkey.dashclicks.com",
          "type": "CNAME",
          "data": "s1.domainkey.u12345678.wl.sendgrid.net",
          "valid": false
        },
        "dkim2": {
          "host": "s2._domainkey.dashclicks.com",
          "type": "CNAME",
          "data": "s2.domainkey.u12345678.wl.sendgrid.net",
          "valid": false
        },
        "dmarc": {
          "host": "_dmarc.dashclicks.com",
          "type": "TXT",
          "data": "v=DMARC1;p=none",
          "valid": false
        }
      }
    }
  ]
}

DNS Configuration

After adding a domain, configure the following DNS records in your domain registrar:

1. Mail CNAME Record:

Host: mail.dashclicks.com
Type: CNAME
Value: u12345678.wl.sendgrid.net
TTL: 3600

2. DKIM1 CNAME Record:

Host: s1._domainkey.dashclicks.com
Type: CNAME
Value: s1.domainkey.u12345678.wl.sendgrid.net
TTL: 3600

3. DKIM2 CNAME Record:

Host: s2._domainkey.dashclicks.com
Type: CNAME
Value: s2.domainkey.u12345678.wl.sendgrid.net
TTL: 3600

4. DMARC TXT Record:

Host: _dmarc.dashclicks.com
Type: TXT
Value: v=DMARC1;p=none
TTL: 3600

DNS Propagation Time: 5-30 minutes (varies by DNS provider)

Validate Domain

Endpoint: POST /v1/integrations/sendgrid/subusers/domains/:domain_id/validate

Purpose: Verify DNS records are correctly configured

Path Parameters:

• domain_id (required) - Sendgrid domain ID

Sendgrid API:

POST https://api.sendgrid.com/v3/whitelabel/domains/{domain_id}/validate
Authorization: Bearer {SENDGRID_API_KEY}
On-Behalf-Of: {subuser_username}

Response:

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "id": 12345678,
    "valid": true,
    "validation_results": {
      "mail_cname": {
        "valid": true,
        "reason": null
      },
      "dkim1": {
        "valid": true,
        "reason": null
      },
      "dkim2": {
        "valid": true,
        "reason": null
      }
    }
  }
}

Validation Failures:

{
  "success": true,
  "message": "SUCCESS",
  "data": {
    "id": 12345678,
    "valid": false,
    "validation_results": {
      "mail_cname": {
        "valid": false,
        "reason": "Expected CNAME to match u12345678.wl.sendgrid.net but found none."
      },
      "dkim1": {
        "valid": true,
        "reason": null
      },
      "dkim2": {
        "valid": true,
        "reason": null
      }
    }
  }
}

Common Validation Errors:

Error	Cause	Solution
CNAME not found	DNS not configured	Add DNS records
CNAME value mismatch	Incorrect value	Update to correct Sendgrid value
DNS not propagated	Waiting for propagation	Wait 5-30 minutes, retry validation
TTL too high	Slow updates	Reduce TTL to 3600 or lower
Multiple CNAME records	Duplicate records	Remove duplicates, keep one
Wrong subdomain configured	Typo in subdomain	Delete and recreate with correct

Delete Domain

Endpoint: DELETE /v1/integrations/sendgrid/subusers/domains/:domain_id

Purpose: Remove domain from subuser

Path Parameters:

• domain_id (required) - Sendgrid domain ID

Process:

1. Verify domain belongs to subuser
2. Delete via Sendgrid API:

   DELETE https://api.sendgrid.com/v3/whitelabel/domains/{domain_id}
   Authorization: Bearer {SENDGRID_API_KEY}
   On-Behalf-Of: {subuser_username}

3. Update database to remove domain from array
4. Delete associated user emails from user.sendgrid_emails

Response:

{
  "success": true,
  "message": "Domain deleted successfully"
}

📦 SubUserCollection Model

Purpose: Subuser and domain document management

Methods:

getSubUserByAccountID()

SubUserCollection.getSubUserByAccountID(accountID);
// Returns: { isEmpty: boolean, doc: account._doc }

getSubUserByUserID()

SubUserCollection.getSubUserByUserID(userID);
// Returns: { isEmpty: boolean, doc: account._doc }

getSubUserDocByUsername()

SubUserCollection.getSubUserDocByUsername(username);
// Returns: { isEmpty: boolean, doc: account._doc }

addSubUserDoc()

SubUserCollection.addSubUserDoc({
  account_id,
  sendgrid: {
    subuser: { username, user_id, email, disabled },
    domain_assigned: true,
    domains: [],
  },
});
// Returns: subuser object

deleteSubUserDoc()

SubUserCollection.deleteSubUserDoc(docID);
// Sets sendgrid=null on account

updateSubUserStatusDoc()

SubUserCollection.updateSubUserStatusDoc(docID, disabled);
// Updates sendgrid.subuser.disabled

getSubUserDomainDocByUserID()

SubUserCollection.getSubUserDomainDocByUserID(userID, domainID);
// Returns: { isEmpty: boolean, doc: account._doc }

addSubUserDomainDoc()

SubUserCollection.addSubUserDomainDoc(docID, sendgridDomain);
// Adds DMARC DNS record automatically
// Pushes to sendgrid.domains array

updateDomain()

SubUserCollection.updateDomain(docID, domainStatus);
// Updates DNS validation results
// Returns: { isEmpty: boolean, doc: domain }

deleteSubUserDomainDoc()

SubUserCollection.deleteSubUserDomainDoc(docID, newDomains);
// Replaces entire domains array

deleteUserEmailDoc()

SubUserCollection.deleteUserEmailDoc(userId, emails);
// Pulls emails from user.sendgrid_emails array

🎛️ SubUserController

Location: Controllers/SubUserController.js

Key Methods

createSubUsers()

• Route: POST /v1/integrations/sendgrid/subusers
• Validation: { username: string.required, email: email.required }
• Logic: Generate password → Get IP → Create subuser → Assign domain → Store in DB

updateSubUser()

• Route: PUT /v1/integrations/sendgrid/subusers/:id
• Body: { disabled: boolean }
• Logic: Get subuser → Update via API → Update database

deleteSubUser()

• Route: DELETE /v1/integrations/sendgrid/subusers/:id
• Logic: Get username → Delete via API → Remove from database

getSubUserReputation()

• Route: GET /v1/integrations/sendgrid/subusers/:id/reputation
• Logic: Query Sendgrid reputation API → Return score

subUserAddDomain()

• Route: POST /v1/integrations/sendgrid/subusers/domains
• Logic: Get subuser → Create domain → Auto-add DMARC → Update DB

subUserValidateDomain()

• Route: POST /v1/integrations/sendgrid/subusers/domains/:domain_id/validate
• Logic: Validate via API → Update validation status in DB

subUserDeleteDomain()

• Route: DELETE /v1/integrations/sendgrid/subusers/domains/:domain_id
• Logic: Verify ownership → Delete via API → Remove from DB → Delete user emails

🧪 Testing

Test Subuser Creation

curl -X POST http://localhost:5003/v1/e/sendgrid/subusers \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "dashclicks_test_acc",
    "email": "subuser@test.com"
  }'

Test Domain Addition

curl -X POST http://localhost:5003/v1/e/sendgrid/subusers/domains \
  -H "Authorization: Bearer {jwt_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "test.com",
    "subdomain": "mail"
  }'

Test Domain Validation

curl -X POST http://localhost:5003/v1/e/sendgrid/subusers/domains/12345678/validate \
  -H "Authorization: Bearer {jwt_token}"

Test Reputation Check

curl -X GET http://localhost:5003/v1/e/sendgrid/subusers/{account_id}/reputation \
  -H "Authorization: Bearer {jwt_token}"

⚠️ Important Notes

• 🏢 One Subuser Per Account: Each DashClicks account gets exactly one subuser
• 🔑 Random Passwords: Passwords auto-generated for security
• 📧 Default Domain: Subusers automatically assigned default Sendgrid domain
• 🌐 Custom Domains: Optional - improves deliverability and branding
• ✅ DNS Validation Required: Domains must be validated before use
• 📊 Reputation Tracking: Monitor reputation to maintain high deliverability
• 🔒 IP Assignment: Each subuser assigned dedicated or shared IP
• ⚙️ DMARC Auto-Config: DMARC record automatically added (v=DMARC1;p=none)
• 🗑️ Soft Delete: Subuser deletion sets sendgrid: null (preserves history)
• 🔄 Domain Reassignment: Domains can be moved between subusers

📈 Best Practices

Subuser Management

1. Create Early: Set up subuser during account onboarding
2. Monitor Reputation: Check regularly (weekly/monthly)
3. Use Descriptive Usernames: Follow naming convention (e.g., dashclicks_acc_{id})
4. Enable/Disable vs Delete: Use enable/disable for temporary suspension

Domain Configuration

1. Verify DNS Access: Ensure customer can modify DNS records
2. Use Short TTL: Set TTL to 3600 for faster changes
3. Validate After Propagation: Wait 5-30 minutes before validating
4. Monitor Validation Status: Re-validate periodically
5. Use Subdomains: Recommend mail. or email. subdomain

Reputation Management

1. Start Slow: Gradually increase sending volume for new subusers
2. Monitor Bounces: High bounce rate damages reputation
3. Respect Unsubscribes: Process immediately to avoid spam complaints
4. Use Double Opt-In: Confirm email addresses before adding to list
5. Clean Lists Regularly: Remove inactive/invalid addresses

🚨 Troubleshooting

Domain Validation Failing

Diagnosis:

1. Check DNS records are configured:

   dig mail.yourdomain.com CNAME
   dig s1._domainkey.yourdomain.com CNAME
   dig s2._domainkey.yourdomain.com CNAME
   dig _dmarc.yourdomain.com TXT

2. Wait for DNS propagation (5-30 minutes)

3. Retry validation endpoint

4. Check Sendgrid dashboard for validation status

Low Reputation Score

Common Causes:

• High bounce rate (>5%)
• Spam complaints (>0.1%)
• Sending to unverified emails
• Rapid volume increase
• Poor list hygiene

Solutions:

• Clean email list
• Enable double opt-in
• Monitor DND list
• Reduce sending volume temporarily
• Improve email content quality

🔗 Related Documentation

• Sendgrid Subusers API
• Domain Authentication
• Sender Reputation
• DNS Configuration Guide
• Authentication
• Email Sending
• Webhooks