SendGrid Users API

openapi: 3.2.0
info:
  title: Twilio SendGrid User Users 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.


    See **Account Details** for more information. You can also manage your user settings in the SendGrid application user interface.'
  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
security:
- BearerAuth: []
tags:
- name: Users API
  description: Twilio SendGrid Users API.
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.**


        Your 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.**


        Each 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.'
      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.**


        Any 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:
    Type:
      type: string
      enum:
      - free
      - paid
    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
    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'
  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 <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: <subuser-username>`). 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
  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.
externalDocs:
  description: Twilio SendGrid's official developer documentation.
  url: https://www.twilio.com/docs/sendgrid