Rate this page:

How to Create a Subuser with the API

Creating a new subuser through SendGrid's API is a multi-step process. This guide will walk you through the necessary steps to create a new subuser account using only API calls.

Establish the New Subuser (required)

With the subuser creation API call you will be able to establish the new subuser's account and profile settings. This call will create the new subuser account. However, it does not apply the sending IP for the account, nor does it establish a domain authentication entry or enable website/SMTP access for the subuser.

Call Example

https://api.sendgrid.com/apiv2/customer.add.json?api_user=ryan.burrer@sendgrid.com&api_key=xxxxxx&username=newsubuser_username&website=yourdomain.com&password=newsubuser_password&confirm_password=newsubuser_password&first_name=Ryan&last_name=Burrer&address=555_anystreet&city=any_city&state=CO&zip=80203&email=example@example.com&country=US&phone=555-5555

Success Message

Failure Message


Assign an IP to be Used by the New Subuser (required)

Now that you have created the new subuser account, you will need to add an IP so that it can send emails. We advise that you first find an available IP for this subuser. You can do so by using the following call:

Call Example

https://api.sendgrid.com/apiv2/customer.ip.xml?api_user=ryan.burrer@sendgrid.com&api_key=xxxxxx&list=all

When defining the parameter 'list', there are a few options you can choose:

  • All - Will list all of the IPs on your account, taken or available.
  • Free - Will list all the free IPs on your account. For instance, if an IP is in use by a subuser or parent account then that IP will not be listed.
  • Taken - Will list all of the IP addresses that are assigned to your parent and subuser accounts.
  • Available - Will list all of the unassigned IP addresses for the account. If a subuser is deactivated _and it _is assigned an IP, that IP will show up on this list since that IP address is not technically in use.
    Response Example

After you have selected the IP that you wish to assign to your subuser account, make the API call to append the IP address.

Call Example

https://api.sendgrid.com/apiv2/customer.sendip.json?api_user=ryan.burrer@sendgrid.com&api_key=xxxxxx&task=append&set=specify&user=newsubuser_username&ip[]=255.255.255.250&ip[]=255.255.255.255

When defining this call's 'set' parameter, you have a few options for appending the subuser's IP:

  • None - removes all of the IPs on the associated account.
  • All - applies all of the possible IPs to the account.
  • Specify - Specify the IPs to the subuser
    Success Message

Failure Message

Assign a domain authentication for the Subuser Account (optional)

After you have created the subuser account and have appended an IP address, you are now ready to assign an existing authenticated domain to the account. If you have not yet created the required records for authenticating your chosen domain then this step should be skipped.

First, you should find out what authenticated domains you have associated with your account. This call will list your available authenticated domains:

Call Example

https://api.sendgrid.com/apiv2/customer.whitelabel.json?api\_user=ryan.burrer@sendgrid.com&api\_key=xxxxxx&task=list

Response Example

The API response above shows that email.sendgrid.com and email.example.com are both already established domain entries, and can be used by this subuser. If none are displayed then the next step in this process should be skipped.

If you have an authenticated domain entry that you wish to apply to your subuser then you will need to append the authenticated domain entry to your subuser:

Call Example

https://api.sendgrid.com/apiv2/customer.whitelabel.json?api_user=ryan.burrer@sendgrid.com&api_key=xxxxxx&task=append&user=newsubuser_username&mail_domain=YOUR.ALREADY.EXISTING.AUTHENTICATED_DOMAIN

Success Message

Failure Message

Authenticating the Subuser to Have Website/SMTP Access (required)

The final step in creating your new subuser requires you to activate the subuser account so that they have a website and SMTP access.

Call Example

https://api.sendgrid.com/apiv2/customer.auth.json?api_user=ryan.burrer@sendgrid.com&api_key=xxxxxx&user=newsubuser_username&password=newsubuser_password

Success Message

Failure Message

Additional Resources

Rate this page:

Need some help?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the SendGrid tag on Stack Overflow.

        
        
        

        Thank you for your feedback!

        We are always striving to improve our documentation quality, and your feedback is valuable to us. Please select the reason(s) for your feedback or provide additional information about how we can improve:

        Sending your feedback...
        🎉 Thank you for your feedback!
        Something went wrong. Please try again.

        Thanks for your feedback!

        Refer us and get $10 in 3 simple steps!

        Step 1

        Get link

        Get a free personal referral link here

        Step 2

        Give $10

        Your user signs up and upgrade using link

        Step 3

        Get $10

        1,250 free SMSes
        OR 1,000 free voice mins
        OR 12,000 chats
        OR more