# Create Subuser ## API Overview For more information about Subusers, visit the [longform Subusers documentation](/docs/sendgrid/ui/account-and-settings/subusers/). You can also [manage Subusers in the SendGrid console](https://app.sendgrid.com/settings/subusers). ## Operation overview ```json {"path":"https://api.sendgrid.com/v3/subusers","method":"post","servers":[{"url":"https://api.sendgrid.com","description":"for global users and subusers"},{"url":"https://api.eu.sendgrid.com","description":"for EU regional subusers"}]} ``` **This endpoint allows you to create a new subuser.** ## Operation details ### Authentication API Key ### Headers ```json [{"in":"header","name":"Authorization","required":true,"default":"Bearer <>","schema":{"type":"string"}}] ``` ### Request body ```json {"schema":{"type":"object","required":["username","email","password","ips"],"example":{"username":"John@example.com","email":"John@example.com","password":"johns_password","ips":["1.1.1.1","2.2.2.2"],"region":"global","include_region":true},"properties":{"username":{"type":"string","description":"The username for this subuser."},"email":{"type":"string","description":"The email address of the subuser.","format":"email"},"password":{"type":"string","description":"The password this subuser will use when logging into SendGrid."},"ips":{"type":"array","description":"The IP addresses that should be assigned to this subuser.","items":{"type":"string","format":"ipv4"}},"region":{"type":"string","description":"The region this Subuser should be assigned to. Can be `global` or `eu`. (Regional email is in Public Beta and requires SendGrid Pro plan or above.).","default":"global","enum":["global","eu"],"refName":"Region1","modelName":"Region1"},"include_region":{"type":"boolean","description":"A flag that determines if the Subuser's region should be returned in the response. (Regional email is in Public Beta and requires SendGrid Pro plan or above.)","default":false}}},"encodingType":"application/json"} ``` ### Responses ```json [{"responseCode":"200","schema":{"description":"","content":{"application/json":{"schema":{"title":"Subuser::POST","type":"object","required":["username","user_id","email"],"example":{"username":"example_subuser","user_id":1234,"email":"example@example.com","credit_allocation":{"type":"unlimited"},"region":"global"},"refName":"SubuserPost","modelName":"SubuserPost","properties":{"username":{"type":"string","description":"The username of the subuser."},"user_id":{"type":"number","description":"The user ID for this subuser."},"email":{"type":"string","description":"The email address for this subuser.","format":"email"},"credit_allocation":{"type":"object","properties":{"type":{"type":"string"}}},"region":{"type":"string","description":"The region this Subuser is assigned to. The property is returned only if the `include_region` parameter is included and set to `true` in the API request.","default":"global","enum":["global","eu"],"refName":"Region3","modelName":"Region3"}}},"examples":{"response":{"value":{"username":"example_subuser","user_id":1234,"email":"example@example.com","credit_allocation":{"type":"unlimited"}}}}}}}},{"responseCode":"400","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"errors":[{"field":"field_name","message":"error message"}]},"refName":"ErrorResponse","modelName":"ErrorResponse","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string","description":"An error message."},"field":{"description":"When applicable, this property value will be the field that generated the error.","nullable":true,"type":"string"},"help":{"type":"object","description":"When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error."}}}},"id":{"type":"string","description":"When applicable, this property value will be an error ID."}}},"examples":{"response":{"value":{"errors":[{"message":"username exists"},{"message":"unable to validate IPs at this time"}]}}}}}}},{"responseCode":"401","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"errors":[{"field":"field_name","message":"error message"}]},"refName":"ErrorResponse","modelName":"ErrorResponse","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string","description":"An error message."},"field":{"description":"When applicable, this property value will be the field that generated the error.","nullable":true,"type":"string"},"help":{"type":"object","description":"When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error."}}}},"id":{"type":"string","description":"When applicable, this property value will be an error ID."}}},"examples":{"response":{"value":{"errors":[{"field":null,"message":"authorization required"}]}}}}}}},{"responseCode":"403","schema":{"description":"","content":{"application/json":{"schema":{"type":"object","example":{"errors":[{"field":"field_name","message":"error message"}]},"refName":"ErrorResponse","modelName":"ErrorResponse","properties":{"errors":{"type":"array","items":{"type":"object","properties":{"message":{"type":"string","description":"An error message."},"field":{"description":"When applicable, this property value will be the field that generated the error.","nullable":true,"type":"string"},"help":{"type":"object","description":"When applicable, this property value will be helper text or a link to documentation to help you troubleshoot the error."}}}},"id":{"type":"string","description":"When applicable, this property value will be an error ID."}}},"examples":{"response":{"value":{"errors":[{"message":"you dont have permission to access this resource"}]}}}}}}},{"responseCode":"500","schema":{"description":"","content":{"application/json":{"schema":{"type":"object"},"examples":{"response":{"value":{"errors":[{"message":"unable to validate IPs at this time"}]}}}}}}}] ``` Create Subuser ```js const client = require("@sendgrid/client"); client.setApiKey(process.env.SENDGRID_API_KEY); const data = { username: "John@example.com", email: "John@example.com", password: "johns_password", ips: ["1.1.1.1", "2.2.2.2"], region: "global", include_region: true, }; const request = { url: `/v3/subusers`, method: "POST", body: data, }; client .request(request) .then(([response, body]) => { console.log(response.statusCode); console.log(response.body); }) .catch((error) => { console.error(error); }); ``` ```python import os from sendgrid import SendGridAPIClient sg = SendGridAPIClient(os.environ.get("SENDGRID_API_KEY")) data = { "username": "John@example.com", "email": "John@example.com", "password": "johns_password", "ips": ["1.1.1.1", "2.2.2.2"], "region": "global", "include_region": True, } response = sg.client.subusers.post(request_body=data) print(response.status_code) print(response.body) print(response.headers) ``` ```csharp using System; using System.Collections.Generic; using System.Threading.Tasks; using SendGrid; public class Program { public static async Task Main() { string apiKey = Environment.GetEnvironmentVariable("SENDGRID_API_KEY"); var client = new SendGridClient(apiKey); var data = @"{ ""username"": ""John@example.com"", ""email"": ""John@example.com"", ""password"": ""johns_password"", ""ips"": [ ""1.1.1.1"", ""2.2.2.2"" ], ""region"": ""global"", ""include_region"": true }"; var response = await client.RequestAsync( method: SendGridClient.Method.POST, urlPath: "subusers", requestBody: data); Console.WriteLine(response.StatusCode); Console.WriteLine(response.Body.ReadAsStringAsync().Result); Console.WriteLine(response.Headers.ToString()); } } ``` ```java import com.sendgrid.*; import java.io.IOException; import org.json.JSONObject; import java.util.HashMap; import java.util.Arrays; public class Example { public static void main(String[] args) throws IOException { try { SendGrid sg = new SendGrid(System.getenv("SENDGRID_API_KEY")); Request request = new Request(); request.setMethod(Method.POST); request.setEndpoint("/subusers"); request.setBody(new JSONObject(new HashMap() { { put("username", "John@example.com"); put("email", "John@example.com"); put("password", "johns_password"); put("ips", Arrays.asList("1.1.1.1", "2.2.2.2")); put("region", "global"); put("include_region", true); } }).toString()); Response response = sg.api(request); System.out.println(response.getStatusCode()); System.out.println(response.getBody()); System.out.println(response.getHeaders()); } catch (IOException ex) { throw ex; } } } ``` ```go package main import ( "fmt" "github.com/sendgrid/sendgrid-go" "os" ) func main() { apiKey := os.Getenv("SENDGRID_API_KEY") host := "https://api.sendgrid.com" request := sendgrid.GetRequest(apiKey, "/v3/subusers", host) request.Method = "POST" request.Body = []byte(`{ "username": "John@example.com", "email": "John@example.com", "password": "johns_password", "ips": [ "1.1.1.1", "2.2.2.2" ], "region": "global", "include_region": true }`) response, err := sendgrid.API(request) if err != nil { fmt.Println(err.Error()) os.Exit(1) } else { fmt.Println(response.StatusCode) fmt.Println(response.Body) fmt.Println(response.Headers) } } ``` ```php /sendgrid-php.php'; $apiKey = getenv("SENDGRID_API_KEY"); $sg = new \SendGrid($apiKey); $request_body = json_decode('{ "username": "John@example.com", "email": "John@example.com", "password": "johns_password", "ips": [ "1.1.1.1", "2.2.2.2" ], "region": "global", "include_region": true }'); try { $response = $sg->client->subusers()->post($request_body); print $response->statusCode() . "\n"; print_r($response->headers()); print $response->body() . "\n"; } catch (Exception $ex) { echo "Caught exception: " . $ex->getMessage(); } ``` ```ruby require 'sendgrid-ruby' include SendGrid sg = SendGrid::API.new(api_key: ENV['SENDGRID_API_KEY']) data = JSON.parse('{ "username": "John@example.com", "email": "John@example.com", "password": "johns_password", "ips": [ "1.1.1.1", "2.2.2.2" ], "region": "global", "include_region": true }') response = sg.client.subusers.post(request_body: data) puts response.status_code puts response.headers puts response.body ``` ```bash curl -X POST "https://api.sendgrid.com/v3/subusers" \ --header "Authorization: Bearer $SENDGRID_API_KEY" \ --header "Content-Type: application/json" \ --data '{"username": "John@example.com", "email": "John@example.com", "password": "johns_password", "ips": ["1.1.1.1", "2.2.2.2"], "region": "global", "include_region": true}' ```