{ "openapi": "3.1.0", "security": [ { "BearerAuth": [] } ], "info": { "title": "Twilio SendGrid IP Address API", "summary": "The Twilio SendGrid IP Address API allows you to add and manage dedicated IP addresses and IP Pools for your SendGrid account and Subusers.", "description": "The Twilio SendGrid IP Address API allows you to add and manage dedicated IP addresses and IP Pools for your SendGrid account and Subusers. If you are sending any significant amount of email, SendGrid typically suggests sending from dedicated IPs. It's also best to send marketing and transactional emails from separate IP addresses. In order to do this, you'll need to set up IP Pools, which are groups of dedicated IP addresses you define to send particular types of messages. See the [**Dedicated IP Addresses**](https://docs.sendgrid.com/ui/account-and-settings/dedicated-ip-addresses) for more information about obtaining and allocating IPs.", "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": "ips" } }, "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/ips": { "post": { "servers": [ { "url": "https://api.sendgrid.com", "description": "for global users" } ], "operationId": "AddIp", "summary": "Add IPs", "tags": [ "IP Addresses" ], "description": "**This endpoint is for adding a(n) IP Address(es) to your account.**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "The amount of IPs to add to the account." }, "subusers": { "type": "array", "description": "Array of usernames to be assigned a send IP.", "items": { "type": "string" } }, "warmup": { "type": "boolean", "default": false, "description": "Whether or not to warmup the IPs being added." } }, "required": [ "count" ], "example": { "count": 90323478, "subusers": [ "subuser1", "subuser2" ], "warmup": true, "user_can_send": true } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ips": { "type": "array", "description": "List of IP objects.", "items": { "type": "object", "properties": { "ip": { "type": "string", "description": "IP added to account." }, "subusers": { "type": "array", "description": "Array of usernames assigned a send IP.", "items": { "type": "string" } } }, "required": [ "ip", "subusers" ] } }, "remaining_ips": { "type": "integer", "description": "The number of IPs that can still be added to the user." }, "warmup": { "type": "boolean", "description": "Whether or not the IPs are being warmed up." } }, "required": [ "ips", "remaining_ips", "warmup" ] }, "examples": { "response": { "value": { "ips": [ { "ip": "1.2.3.4", "subusers": [ "user", "subuser1" ] }, { "ip": "1.2.3.5", "subusers": [ "user", "subuser1" ] } ], "remaining_ips": 1, "warmup": true } } } } } }, "400": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "one or more subusers do not belong to this user" } ] } } } } } } } }, "get": { "operationId": "ListIp", "summary": "Retrieve all IP addresses", "tags": [ "IP Addresses" ], "description": "**This endpoint allows you to retrieve a paginated list of all assigned and unassigned IPs.**\n\nResponse includes warm up status, pools, assigned subusers, and reverse DNS info. The start_date field corresponds to when warmup started for that IP.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is determined by the aggregate performance of all email traffic sent from it.\n\nYou can use the `limit` query parameter to set the page size. If your list contains more items than the page size permits, you can make multiple requests. Use the `offset` query parameter to control the position in the list from which to start retrieving additional items.", "parameters": [ { "name": "ip", "in": "query", "description": "The IP address to get", "schema": { "type": "string" } }, { "name": "exclude_whitelabels", "in": "query", "description": "Should we exclude reverse DNS records (whitelabels)?", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "`limit` sets the page size, i.e. maximum number of items from the list to be returned for a single API request. If omitted, the default page size is used.", "schema": { "type": "integer", "minimum": 1, "default": 10 } }, { "$ref": "#/components/parameters/PaginationCommonOffset" }, { "name": "subuser", "in": "query", "description": "The subuser you are requesting for.", "schema": { "type": "string" } }, { "name": "sort_by_direction", "in": "query", "description": "The direction to sort the results.", "schema": { "type": "string", "$ref": "#/components/schemas/SortByDirection" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "ip": { "type": "string", "description": "An IP address." }, "subusers": { "type": "array", "description": "The subusers that are able to send email from this IP.", "items": { "type": "string" } }, "rdns": { "type": "string", "description": "The reverse DNS record for this IP address." }, "pools": { "type": "array", "description": "The IP pools that this IP has been added to.", "items": { "type": "string" } }, "warmup": { "type": "boolean", "description": "Indicates if this IP address is currently warming up." }, "start_date": { "description": "The date that the IP address was entered into warmup.", "nullable": true, "type": "number" }, "whitelabeled": { "type": "boolean", "description": "Indicates if this IP address is associated with a reverse DNS record." }, "assigned_at": { "description": "The date that the IP address was assigned to the user.", "nullable": true, "type": "integer" } }, "required": [ "ip", "subusers", "pools", "warmup", "start_date", "whitelabeled", "assigned_at" ] } }, "examples": { "response": { "value": [ { "ip": "192.168.1.1", "pools": [ "pool1", "pool2" ], "whitelabeled": false, "start_date": 1409616000, "subusers": [ "tim@sendgrid.net" ], "warmup": false, "assigned_at": 1482883200 }, { "ip": "208.115.214.22", "pools": [], "whitelabeled": true, "rdns": "o1.email.example.com", "start_date": 1409616000, "subusers": [], "warmup": false, "assigned_at": 1482883200 } ] } } } } } } } }, "/v3/ips/{ip_address}": { "parameters": [ { "name": "ip_address", "in": "path", "description": "The IP address you are retrieving the IP pools for.", "required": true, "schema": { "type": "string" } } ], "get": { "servers": [ { "url": "https://api.sendgrid.com", "description": "for global users" } ], "operationId": "GetIp", "summary": "Retrieve all IP pools an IP address belongs to", "tags": [ "IP Addresses" ], "description": "**This endpoint allows you to see which IP pools a particular IP address has been added to.**\n\nThe same IP address can be added to multiple IP pools.\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "The IP address." }, "subusers": { "type": "array", "description": "The subusers that can send email using this IP address.", "items": { "type": "string" } }, "rdns": { "type": "string", "description": "The reverse DNS record for this IP address." }, "pools": { "type": "array", "description": "The list of IP pools that this IP address belongs to.", "items": { "type": "string" } }, "warmup": { "type": "boolean", "description": "Indicates if this IP address is currently warming up." }, "start_date": { "description": "The date that the IP address was entered into warmup.", "nullable": true, "type": "integer" }, "whitelabeled": { "type": "boolean", "description": "Indicates if this IP address is associated with a reverse DNS record." } }, "required": [ "ip", "subusers", "rdns", "pools", "warmup", "start_date", "whitelabeled" ] }, "examples": { "response": { "value": { "ip": "000.00.00.0", "subusers": [ "subuser1", "subuser2" ], "rdns": "o1.em.example.com", "pools": [ "test1" ], "warmup": false, "start_date": null, "whitelabeled": true } } } } } } } } }, "/v3/ips/assigned": { "servers": [ { "url": "https://api.sendgrid.com", "description": "for global users" } ], "get": { "operationId": "ListAssignedIp", "summary": "Retrieve all assigned IPs", "tags": [ "IP Addresses" ], "description": "**This endpoint allows you to retrieve only assigned IP addresses.**\n\nA single IP address or a range of IP addresses may be dedicated to an account in order to send email for multiple domains. The reputation of this IP is based on the aggregate performance of all the senders who use it.", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "title": "List all assigned IPs response", "items": { "type": "object", "properties": { "ip": { "type": "string", "description": "The IP address." }, "pools": { "type": "array", "description": "The IP pools that this IP address has been added to.", "items": { "type": "string" } }, "warmup": { "type": "boolean", "description": "Indicates if this IP address is currently warming up." }, "start_date": { "type": "integer", "description": "The start date that this IP address was entered into warmup." } }, "required": [ "ip", "pools", "warmup", "start_date" ] } }, "examples": { "response": { "value": [ { "ip": "167.89.21.3", "pools": [ "new_test5" ], "warmup": true, "start_date": 1409616000 } ] } } } } } } } }, "/v3/ips/pools": { "post": { "operationId": "CreateIpPool", "summary": "Create an IP pool", "tags": [ "IP Pools" ], "description": "**This endpoint allows you to create an IP pool.**\n\nBefore you can create an IP pool, you need to activate the IP in your SendGrid account: \n\n1. Log into your SendGrid account. \n1. Navigate to **Settings** and then select **IP Addresses**. \n1. Find the IP address you want to activate and then click **Edit**. \n1. Check **Allow my account to send mail using this IP address**.\n1. Click **Save**.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of your new IP pool.", "maxLength": 64 } }, "required": [ "name" ], "example": { "name": "marketing" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpPools200" }, "examples": { "response": { "value": { "name": "marketing" } } } } } } } }, "get": { "operationId": "ListIpPool", "summary": "Retrieve all IP pools", "tags": [ "IP Pools" ], "description": "**This endpoint allows you to get all of your IP pools.**", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/IpPools200" } }, "examples": { "response": { "value": [ { "name": "marketing" }, { "name": "transactional" } ] } } } } } } } }, "/v3/ips/pools/{pool_name}": { "parameters": [ { "name": "pool_name", "in": "path", "description": "The name of the IP pool that you want to retrieve the IP addresses for.", "required": true, "schema": { "type": "string" } } ], "get": { "operationId": "GetIpPool", "summary": "Retrieve all the IPs in a specified pool", "tags": [ "IP Pools" ], "description": "**This endpoint allows you to get all of the IP addresses that are in a specific IP pool.**", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "pool_name": { "type": "string", "description": "The name of the IP pool.", "maxLength": 64 }, "ips": { "description": "The IP addresses that belong to this pool.", "type": "array", "items": { "type": "string" } } } }, "examples": { "response": { "value": { "pool_name": "Sample", "ips": [ "192.168.1.1", "192.158.1.2", "192.138.2.1" ] } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "description": "The name of the error." }, "message": { "type": "string", "description": "A message explaining why the IP addresses could not be listed." } } } } } }, "examples": { "response": { "value": { "errors": [ { "field": "error", "message": "Unable to locate specified IPs Pool" } ] } } } } } } } }, "put": { "operationId": "UpdateIpPool", "summary": "Rename an IP pool", "tags": [ "IP Pools" ], "description": "**This endpoint allows you to update the name of an IP pool.**", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The new name for your IP pool.", "maxLength": 64 } }, "example": { "name": "new_pool_name" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IpPools200" }, "examples": { "response": { "value": { "name": "new_pool_name" } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "nullable": true }, "message": { "type": "string", "description": "A message explaining why the name of your IP pool could not be updated." } } } } } }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "ip pool not found" } ] } } } } } } } }, "delete": { "operationId": "DeleteIpPool", "summary": "Delete an IP pool", "tags": [ "IP Pools" ], "description": "**This endpoint allows you to delete an IP pool.**", "responses": { "204": { "description": "" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "An error explaining why the pool could not be deleted." } } }, "examples": { "response": { "value": { "error": "Unable to locate specified IPs Pool" } } } } } } } } }, "/v3/ips/pools/{pool_name}/ips": { "parameters": [ { "name": "pool_name", "in": "path", "description": "The name of the IP pool you want to add the address to. If the name contains spaces, they must be URL encoded (e.g., \"Test Pool\" becomes \"Test%20Pool\").", "required": true, "schema": { "type": "string" } } ], "post": { "operationId": "AddIpToIpPool", "summary": "Add an IP address to a pool", "tags": [ "IP Pools" ], "description": "**This endpoint allows you to add an IP address to an IP pool.**\n\nYou can add the same IP address to multiple pools. It may take up to 60 seconds for your IP address to be added to a pool after your request is made.\n\nBefore you can add an IP to a pool, you need to activate it in your SendGrid account:\n\n1. Log into your SendGrid account. \n1. Navigate to **Settings** and then select **IP Addresses**. \n1. Find the IP address you want to activate and then click **Edit**. \n1. Check **Allow my account to send mail using this IP address**.\n1. Click **Save**.\n\nYou can retrieve all of your available IP addresses from the \"Retrieve all IP addresses\" endpoint.", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "The IP address that you want to add to the named pool." } }, "example": { "ip": "0.0.0.0" } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "The IP address." }, "pools": { "type": "array", "description": "The IP pools that this IP address has been added to.", "items": { "type": "string" } }, "start_date": { "type": "integer", "description": "A Unix timestamp indicating when the warmup process began for the added IP address." }, "warmup": { "type": "boolean", "description": "Indicates if the IP address is in warmup." } }, "required": [ "ip", "pools", "start_date", "warmup" ] }, "examples": { "response": { "value": { "ip": "000.00.00.0", "pools": [ "test1" ], "start_date": 1409616000, "warmup": true } } } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "description": "The error returned.", "items": { "type": "object", "properties": { "field": { "type": "string", "nullable": true }, "message": { "type": "string", "description": "A message explaining why the IP address could not be added to the IP Pool." } } } } } }, "examples": { "response": { "value": { "errors": [ { "field": null, "message": "resource not found" } ] } } } } } } } } }, "/v3/ips/pools/{pool_name}/ips/{ip}": { "parameters": [ { "name": "pool_name", "in": "path", "description": "The name of the IP pool that you are removing the IP address from.", "required": true, "schema": { "type": "string" } }, { "name": "ip", "in": "path", "description": "The IP address that you wish to remove.", "required": true, "schema": { "type": "string" } } ], "delete": { "operationId": "DeleteIpFromIpPool", "summary": "Remove an IP address from a pool", "tags": [ "IP Pools" ], "description": "**This endpoint allows you to remove an IP address from an IP pool.**", "responses": { "204": { "description": "" }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "An error explaining why the IP address could not be removed from the IP pool." } } }, "examples": { "response": { "value": { "error": "Unable to locate specified IPs Pool" } } } } } } } } }, "/v3/ips/remaining": { "get": { "operationId": "ListRemainingIpCount", "summary": "Get remaining IPs count", "tags": [ "IP Addresses" ], "description": "**This endpoint gets amount of IP Addresses that can still be created during a given period and the price of those IPs.**", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "remaining": { "type": "integer", "description": "The number of IPs that can still be added to the user." }, "period": { "type": "string", "description": "The length of time until user can add more IPs." }, "price_per_ip": { "type": "number", "description": "The current cost to add an IP." } }, "required": [ "remaining", "period", "price_per_ip" ] } } }, "required": [ "results" ] }, "examples": { "response": { "value": { "results": [ { "remaining": 2, "period": "month", "price_per_ip": 20 } ] } } } } } } } } } }, "components": { "schemas": { "IpPools200": { "title": "IP Pools: Pool Resp", "type": "object", "properties": { "name": { "type": "string", "description": "The name of the IP pool." } }, "example": { "name": "sunt sint enim" } }, "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" } ] } }, "SortByDirection": { "type": "string", "enum": [ "desc", "asc" ] } }, "responses": {}, "parameters": { "PaginationCommonOffset": { "name": "offset", "in": "query", "required": false, "description": "The number of items in the list to skip over before starting to retrieve the items for the requested page. The default `offset` of `0` represents the beginning of the list, i.e. the start of the first page. To request the second page of the list, set the `offset` to the page size as determined by `limit`. Use multiples of the page size as your `offset` to request further consecutive pages. E.g. assume your page size is set to `10`. An `offset` of `10` requests the second page, an `offset` of `20` requests the third page and so on, provided there are sufficiently many items in your list.", "schema": { "type": "integer", "minimum": 0, "default": 0 } } }, "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": "IP Addresses", "description": "Twilio SendGrid IP Address API Operations" }, { "name": "IP Pools", "description": "Twilio SendGrid IP Address Pool API Operations" } ], "externalDocs": { "description": "Twilio SendGrid's official developer documentation.", "url": "https://www.twilio.com/docs/sendgrid" } }