{ "openapi": "3.1.0", "security": [ { "BearerAuth": [] } ], "info": { "title": "Twilio SendGrid User API", "summary": "The Twilio SendGrid User API allows you to modify the settings of a SendGrid user account such as the user's email address or username.", "description": "The Twilio SendGrid User API allows you to modify the settings of a SendGrid user account such as the user's email address or username. Keeping your user profile up to date helps SendGrid verify who you are and share important communications with you.\n\nSee [**Account Details**](https://docs.sendgrid.com/ui/account-and-settings/account) for more information. You can also manage your user settings in the [SendGrid application user interface](https://app.sendgrid.com/account/details).", "termsOfService": "https://www.twilio.com/legal/tos", "contact": { "name": "Twilio SendGrid Support", "url": "https://support.sendgrid.com/hc/en-us" }, "license": { "name": "MIT", "url": "https://code.hq.twilio.com/twilio/sendgrid-oas/blob/main/LICENSE" }, "version": "1.0.0", "x-sendgrid": { "libraryPackage": "user" } }, "servers": [ { "url": "https://api.sendgrid.com", "description": "for global users and subusers" }, { "url": "https://api.eu.sendgrid.com", "description": "for EU regional subusers" } ], "paths": { "/v3/user/account": { "get": { "operationId": "ListAccount", "summary": "Get a user's account information.", "tags": [ "Users API" ], "description": "**This endpoint allows you to retrieve your user account details.**\n\nYour user's account information includes the user's account type and reputation.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "title": "GET User Account response", "type": "object", "properties": { "type": { "type": "string", "description": "The type of account for this user.", "$ref": "#/components/schemas/Type" }, "reputation": { "type": "number", "description": "The sender reputation for this user." } }, "required": [ "type", "reputation" ] }, "examples": { "response": { "value": { "reputation": 100, "type": "paid" } } } } } } } } }, "/v3/user/credits": { "get": { "operationId": "ListCredit", "summary": "Retrieve your credit balance", "tags": [ "Users API" ], "description": "**This endpoint allows you to retrieve the current credit balance for your account.**\n\nEach account has a credit balance, which is a base number of emails it can send before receiving per-email charges. For more information about credits and billing, see [Billing and Plan details information](https://sendgrid.com/docs/ui/account-and-settings/billing/).", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "remain": { "type": "integer", "description": "The remaining number of credits available on your account." }, "total": { "type": "integer", "description": "The total number of credits assigned to your account." }, "overage": { "type": "integer", "description": "The number of overdrawn credits for your account." }, "used": { "type": "integer", "description": "The number of credits that you have used." }, "last_reset": { "type": "string", "description": "The date that your credit balance was last reset." }, "next_reset": { "type": "string", "description": "The next date that your credit balance will be reset." }, "reset_frequency": { "type": "string", "description": "The frequency at which your credit balance will be reset." } }, "required": [ "remain", "total", "overage", "used", "last_reset", "next_reset", "reset_frequency" ] }, "examples": { "response": { "value": { "remain": 200, "total": 200, "overage": 0, "used": 0, "last_reset": "2013-01-01", "next_reset": "2013-02-01", "reset_frequency": "monthly" } } } } } } } } }, "/v3/user/email": { "get": { "operationId": "ListEmail", "summary": "Retrieve your account email address", "tags": [ "Users API" ], "description": "**This endpoint allows you to retrieve the email address currently on file for your account.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address currently on file for your account.", "format": "email" } }, "required": [ "email" ] }, "examples": { "response": { "value": { "email": "test@example.com" } } } } } } } }, "put": { "operationId": "UpdateEmail", "summary": "Update your account email address", "tags": [ "Users API" ], "description": "**This endpoint allows you to update the email address currently on file for your account.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The new email address that you would like to use for your account." } }, "example": { "email": "example@example.com" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The current email address on file for your account.", "format": "email" } }, "required": [ "email" ] }, "examples": { "response": { "value": { "email": "example@example.com" } } } } } } } } }, "/v3/user/password": { "put": { "operationId": "UpdatePassword", "summary": "Update your password", "tags": [ "Users API" ], "description": "**This endpoint allows you to update your password.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "new_password": { "type": "string", "description": "The new password you would like to use for your account." }, "old_password": { "type": "string", "description": "The old password for your account." } }, "required": [ "new_password", "old_password" ], "example": { "new_password": "new_password", "old_password": "old_password" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } } } } }, "/v3/user/profile": { "get": { "operationId": "ListProfile", "summary": "Get a user's profile", "description": "**This endpoint allows you to retrieve your current profile details.**", "tags": [ "Users API" ], "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "title": "GET User Profile response", "type": "object", "properties": { "address": { "type": "string", "description": "The user's address." }, "address2": { "type": "string", "description": "The second line of the user's address." }, "city": { "type": "string", "description": "The user's city." }, "company": { "type": "string", "description": "The name of the user's company." }, "country": { "type": "string", "description": "The user's country." }, "first_name": { "type": "string", "description": "The user's first name." }, "last_name": { "type": "string", "description": "The user's last name." }, "phone": { "type": "string", "description": "The user's phone number." }, "state": { "type": "string", "description": "The user's state." }, "website": { "type": "string", "description": "The user's website URL." }, "zip": { "type": "string", "description": "The user's zip code." } }, "required": [ "address", "city", "company", "country", "first_name", "last_name", "phone", "state", "website", "zip" ] }, "examples": { "response": { "value": { "address": "814 West Chapman Avenue", "address2": "", "city": "Orange", "company": "SendGrid", "country": "US", "first_name": "Test", "last_name": "User", "phone": "555-555-5555", "state": "CA", "website": "http://www.sendgrid.com", "zip": "92868" } } } } } } } }, "patch": { "operationId": "UpdateProfile", "summary": "Update a user's profile", "tags": [ "Users API" ], "description": "**This endpoint allows you to update your current profile details.**\n\nAny one or more of the parameters can be updated via the PATCH `/user/profile` endpoint. You must include at least one when you PATCH.", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfile" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserProfile" }, "examples": { "response": { "value": { "address": "814 West Chapman Avenue", "address2": "", "city": "Orange", "company": "SendGrid", "country": "US", "first_name": "Example", "last_name": "User", "phone": "555-555-5555", "state": "CA", "website": "http://www.sendgrid.com", "zip": "92868" } } } } } }, "401": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "authorization required" } ] } } } } } } } } }, "/v3/user/username": { "get": { "operationId": "ListUsername", "summary": "Retrieve your username", "tags": [ "Users API" ], "description": "**This endpoint allows you to retrieve your current account username.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "Your account username." }, "user_id": { "type": "integer", "description": "The user ID for your account." } }, "required": [ "username", "user_id" ] }, "examples": { "response": { "value": { "username": "test_username", "user_id": 1 } } } } } } } }, "put": { "operationId": "UpdateUsername", "summary": "Update your username", "tags": [ "Users API" ], "description": "**This endpoint allows you to update the username for your account.**", "parameters": [ { "$ref": "#/components/parameters/OnBehalfOf" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "The new username you would like to use for your account." } }, "example": { "username": "test_username" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "The current username on file for your account." } }, "required": [ "username" ] }, "examples": { "response": { "value": { "username": "test_username" } } } } } } } } } }, "components": { "schemas": { "UserProfile": { "title": "User: Profile", "type": "object", "properties": { "address": { "type": "string", "description": "The street address for this user profile." }, "address2": { "type": "string", "description": "An optional second line for the street address of this user profile." }, "city": { "type": "string", "description": "The city for the user profile." }, "company": { "type": "string", "description": "That company that this user profile is associated with." }, "country": { "type": "string", "description": "Th country of this user profile." }, "first_name": { "type": "string", "description": "The first name of the user." }, "last_name": { "type": "string", "description": "The last name of the user." }, "phone": { "type": "string", "description": "The phone number for the user." }, "state": { "type": "string", "description": "The state for this user." }, "website": { "type": "string", "description": "The website associated with this user." }, "zip": { "type": "string", "description": "The zip code for this user." } }, "example": { "address": "1451 Larimer Street, 3rd floor", "address2": "", "city": "Denver, CO", "company": "SendGrid", "country": "US", "first_name": "Matthew", "last_name": "Bernier", "phone": "7208788003", "state": "CO", "website": "http://sendgrid.com", "zip": "80202" } }, "ErrorResponse": { "type": "object", "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." } }, "example": { "errors": [ { "field": "field_name", "message": "error message" } ] } }, "Type": { "type": "string", "enum": [ "free", "paid" ] } }, "responses": {}, "parameters": { "OnBehalfOf": { "name": "on-behalf-of", "in": "header", "description": "The `on-behalf-of` header allows you to make API calls from a parent account on behalf of the parent's Subusers or customer accounts. You will use the parent account's API key when using this header. When making a call on behalf of a customer account, the property value should be \"account-id\" followed by the customer account's ID (e.g., `on-behalf-of: account-id `). When making a call on behalf of a Subuser, the property value should be the Subuser's username (e.g., `on-behalf-of: `). See [**On Behalf Of**](https://docs.sendgrid.com/api-reference/how-to-use-the-sendgrid-v3-api/on-behalf-of) for more information.", "required": false, "schema": { "type": "string" } } }, "examples": {}, "requestBodies": {}, "headers": {}, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Twilio SendGrid requires you to authenticate with its APIs using an API key. The API key must be sent as a bearer token in the Authorization header." } } }, "tags": [ { "name": "Users API", "description": "Twilio SendGrid Users API." } ], "externalDocs": { "description": "Twilio SendGrid's official developer documentation.", "url": "https://www.twilio.com/docs/sendgrid" } }