<% body %>Example
\n" } } }, "400": { "$ref": "#/responses/trait:makoErrorResponse:400" }, "401": { "$ref": "#/responses/trait:makoErrorResponse:401" }, "403": { "$ref": "#/responses/trait:makoErrorResponse:403" }, "404": { "$ref": "#/responses/trait:makoErrorResponse:404" }, "500": { "$ref": "#/responses/trait:makoErrorResponse:500" } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_mail_settings-template", "summary": "Retrieve legacy template mail settings", "tags": [ "Settings - Mail" ], "description": "**This endpoint allows you to retrieve your current legacy email template settings.**\n\nThis setting refers to our original email templates. We currently support more fully featured [Dynamic Transactional Templates](https://sendgrid.com/docs/ui/sending-email/how-to-send-an-email-with-dynamic-transactional-templates/).\n\nThe legacy email template setting wraps an HTML template around your email content. This can be useful for sending out marketing email and/or other HTML formatted messages. For instructions on using legacy templates, see how to [\"Create and Edit Legacy Transactional Templates](https://sendgrid.com/docs/ui/sending-email/create-and-edit-legacy-transactional-templates/). For help migrating to our current template system, see [\"Migrating from Legacy Templates\"](https://sendgrid.com/docs/ui/sending-email/migrating-from-legacy-templates/).", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/mail_settings_template" }, "examples": { "application/json": { "enabled": false, "html_content": "<% body %>Example
\n" } } }, "400": { "$ref": "#/responses/trait:makoErrorResponse:400" }, "401": { "$ref": "#/responses/trait:makoErrorResponse:401" }, "403": { "$ref": "#/responses/trait:makoErrorResponse:403" }, "404": { "$ref": "#/responses/trait:makoErrorResponse:404" }, "500": { "$ref": "#/responses/trait:makoErrorResponse:500" } }, "security": [ { "Authorization": [] } ] } }, "/mail_settings/bounce_purge": { "patch": { "operationId": "PATCH_mail_settings-bounce_purge", "summary": "Update bounce purge mail settings", "tags": [ "Settings - Mail" ], "description": "**This endpoint allows you to update your current bounce and purge settings.**\n\nThe Bounce Perge setting allows you to set a schedule that Twilio SendGrid will use to automatically delete contacts from your soft and hard bounce suppression lists. The schedule is set in full days by assigning the number of days, an integer, to the `soft_bounces` and/or `hard_bounces` fields.\n\nA hard bounce occurs when an email message has been returned to the sender because the recipient's address is invalid. A hard bounce might occur because the domain name doesn't exist or because the recipient is unknown.\n\nA soft bounce occurs when an email message reaches the recipient's mail server but is bounced back undelivered before it actually reaches the recipient. A soft bounce might occur because the recipient's inbox is full.\n\nYou can also manage this setting in the [Mail Settings section of the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings). You can manage your bounces manually using the [Bounces API](https://sendgrid.api-docs.io/v3.0/bounces-api) or the [Bounces menu in the Twilio SendGrid App](https://app.sendgrid.com/suppressions/bounces).", "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/mail_settings_bounce_purge", "example": { "enabled": true, "hard_bounces": 5, "soft_bounces": 5 } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/mail_settings_bounce_purge" }, "examples": { "application/json": { "enabled": false, "hard_bounces": 5, "soft_bounces": 5 } } }, "400": { "$ref": "#/responses/trait:makoErrorResponse:400" }, "401": { "$ref": "#/responses/trait:makoErrorResponse:401" }, "403": { "$ref": "#/responses/trait:makoErrorResponse:403" }, "404": { "$ref": "#/responses/trait:makoErrorResponse:404" }, "500": { "$ref": "#/responses/trait:makoErrorResponse:500" } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_mail_settings-bounce_purge", "summary": "Retrieve bounce purge mail settings", "tags": [ "Settings - Mail" ], "description": "**This endpoint allows you to retrieve your current bounce and purge settings.**\n\nThe Bounce Perge setting allows you to set a schedule that Twilio SendGrid will use to automatically delete contacts from your soft and hard bounce suppression lists.\n\nA hard bounce occurs when an email message has been returned to the sender because the recipient's address is invalid. A hard bounce might occur because the domain name doesn't exist or because the recipient is unknown.\n\nA soft bounce occurs when an email message reaches the recipient's mail server but is bounced back undelivered before it actually reaches the recipient. A soft bounce might occur because the recipient's inbox is full.\n\nYou can also manage this setting in the [Mail Settings section of the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings). You can manage your bounces manually using the [Bounces API](https://sendgrid.api-docs.io/v3.0/bounces-api) or the [Bounces menu in the Twilio SendGrid App](https://app.sendgrid.com/suppressions/bounces).", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/mail_settings_bounce_purge" }, "examples": { "application/json": { "enabled": false, "soft_bounces": 5, "hard_bounces": 5 } } }, "400": { "$ref": "#/responses/trait:makoErrorResponse:400" }, "401": { "$ref": "#/responses/trait:makoErrorResponse:401" }, "403": { "$ref": "#/responses/trait:makoErrorResponse:403" }, "404": { "$ref": "#/responses/trait:makoErrorResponse:404" }, "500": { "$ref": "#/responses/trait:makoErrorResponse:500" } }, "security": [ { "Authorization": [] } ] } }, "/mail_settings/forward_bounce": { "patch": { "operationId": "PATCH_mail_settings-forward_bounce", "summary": "Update forward bounce mail settings", "tags": [ "Settings - Mail" ], "description": "**This endpoint allows you to update your current bounce forwarding mail settings.**\n\nEnabling the Forward Bounce setting allows you to specify an `email` address to which bounce reports will be forwarded.\n\nYou can also configure the Forward Spam mail settings in the [Mail Settings section of the Twilio SendGrid App](https://app.sendgrid.com/settings/mail_settings).", "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/mail_settings_forward_bounce", "example": { "enabled": true, "email": "bounces@example.com" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/mail_settings_forward_bounce" }, "examples": { "application/json": { "email": "bounces@example.com", "enabled": true } } }, "400": { "$ref": "#/responses/trait:makoErrorResponse:400" }, "401": { "$ref": "#/responses/trait:makoErrorResponse:401" }, "403": { "$ref": "#/responses/trait:makoErrorResponse:403" }, "404": { "$ref": "#/responses/trait:makoErrorResponse:404" }, "500": { "$ref": "#/responses/trait:makoErrorResponse:500" } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_mail_settings-forward_bounce", "summary": "Retrieve forward bounce mail settings", "tags": [ "Settings - Mail" ], "description": "**This endpoint allows you to retrieve your current bounce forwarding mail settings.**\n\nEnabling the Forward Bounce setting allows you to specify `email` addresses to which bounce reports will be forwarded. This endpoint returns the email address you have set to receive forwarded bounces and an `enabled` status indicating if the setting is active.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/mail_settings_forward_bounce" }, "examples": { "application/json": { "enabled": true, "email": "bounces@example.com" } } }, "400": { "$ref": "#/responses/trait:makoErrorResponse:400" }, "401": { "$ref": "#/responses/trait:makoErrorResponse:401" }, "403": { "$ref": "#/responses/trait:makoErrorResponse:403" }, "404": { "$ref": "#/responses/trait:makoErrorResponse:404" }, "500": { "$ref": "#/responses/trait:makoErrorResponse:500" } }, "security": [ { "Authorization": [] } ] } }, "/partner_settings/new_relic": { "patch": { "operationId": "PATCH_partner_settings-new_relic", "summary": "Updates New Relic partner settings.", "tags": [ "Settings - Partner" ], "description": "**This endpoint allows you to update or change your New Relic partner settings.**\n\nOur partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [Partners documentation](https://sendgrid.com/docs/ui/account-and-settings/partners/).\n\nBy integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [SendGrid for New Relic documentation](https://sendgrid.com/docs/ui/analytics-and-reporting/tracking-stats-using-new-relic/).", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "license_key": { "type": "string", "description": "The license key for your New Relic account." }, "enabled": { "type": "boolean", "description": "Indicates if this partner setting is enabled." }, "enable_subuser_statistics": { "type": "boolean", "description": "Indicates if your subuser statistics will be sent to your New Relic Dashboard." } }, "example": { "license_key": "", "enabled": true, "enable_subuser_statistics": true } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/partner_settings_new_relic" }, "examples": { "application/json": { "enable_subuser_statistics": true, "enabled": true, "license_key": "" } } } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_partner_settings-new_relic", "summary": "Returns all New Relic partner settings.", "tags": [ "Settings - Partner" ], "description": "**This endpoint allows you to retrieve your current New Relic partner settings.**\n\nOur partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [Partners documentation](https://sendgrid.com/docs/ui/account-and-settings/partners/).\n\nBy integrating with New Relic, you can send your SendGrid email statistics to your New Relic Dashboard. If you enable this setting, your stats will be sent to New Relic every 5 minutes. You will need your New Relic License Key to enable this setting. For more information, please see our [SendGrid for New Relic documentation](https://sendgrid.com/docs/ui/analytics-and-reporting/tracking-stats-using-new-relic/).", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/partner_settings_new_relic" }, "examples": { "application/json": { "enable_subuser_statistics": false, "enabled": true, "license_key": "" } } } }, "security": [ { "Authorization": [] } ] } }, "/partner_settings": { "get": { "operationId": "GET_partner_settings", "summary": "Returns a list of all partner settings.", "tags": [ "Settings - Partner" ], "description": "**This endpoint allows you to retrieve a list of all partner settings that you can enable.**\n\nOur partner settings allow you to integrate your SendGrid account with our partners to increase your SendGrid experience and functionality. For more information about our partners, and how you can begin integrating with them, please visit our [Partners documentation](https://sendgrid.com/docs/ui/account-and-settings/partners/).", "parameters": [ { "name": "limit", "in": "query", "description": "The number of settings to return per page.", "type": "integer" }, { "name": "offset", "in": "query", "description": "The paging offset.", "type": "integer" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "The title of the partner." }, "enabled": { "type": "boolean", "description": "Indicates if this partner setting has been enabled." }, "name": { "type": "string", "description": "The name of the partner setting." }, "description": { "type": "string", "description": "A description of this partner setting." } }, "required": [ "title", "enabled", "name", "description" ] } } } }, "examples": { "application/json": { "result": [ { "title": "Partner title", "enabled": true, "name": "partner_name", "description": "A description of a partner." } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/teammates": { "post": { "operationId": "POST_v3-teammates", "summary": "Invite teammate", "tags": [ "Teammates" ], "description": "**This endpoint allows you to invite a Teammate to your account via email.**\n\nYou can set a Teammate's initial permissions using the `scopes` array in the request body. Teammate's will receive a minimum set of scopes from Twilio SendGrid that are necessary for the Teammate to function.\n\n**Note:** A teammate invite will expire after 7 days, but you may resend the invitation at any time to reset the expiration date.", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "New teammate's email", "minLength": 5, "maxLength": 255, "pattern": "^.*@.*\\..*" }, "scopes": { "type": "array", "description": "Set to specify list of scopes that teammate should have. Should be empty if teammate is an admin.", "items": { "type": "string" } }, "is_admin": { "type": "boolean", "default": false, "description": "Set to true if teammate should be an admin user" } }, "required": [ "email", "scopes", "is_admin" ], "example": { "email": "teammate1@example.com", "scopes": [ "user.profile.read", "user.profile.update" ], "is_admin": false } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "201": { "description": "", "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Token to identify invite" }, "email": { "type": "string", "description": "Teammate's email address" }, "scopes": { "type": "array", "description": "Initial set of permissions to give to teammate if they accept the invite", "items": {} }, "is_admin": { "type": "boolean", "description": "Set to true if teammate should have admin privileges" } } }, "examples": { "application/json": { "email": "teammate1@example.com", "scopes": [ "user.profile.read", "user.profile.update" ], "is_admin": false } } }, "400": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } } } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_v3-teammates", "summary": "Retrieve all teammates", "tags": [ "Teammates" ], "description": "**This endpoint allows you to retrieve a list of all current Teammates.**\n\nYou can limit the number of results returned using the `limit` query paramater. To return results from a specific Teammate, use the `offset` paramter. The Response Headers will include pagination info.", "parameters": [ { "name": "limit", "in": "query", "description": "Number of items to return", "type": "integer", "default": 500, "minimum": 0, "maximum": 500 }, { "name": "offset", "in": "query", "description": "Paging offset", "type": "integer", "default": 0, "minimum": 0 }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string", "description": "Teammate's username" }, "email": { "type": "string", "description": "Teammate's email" }, "first_name": { "type": "string", "description": "Teammate's first name" }, "last_name": { "type": "string", "description": "Teammate's last name" }, "user_type": { "type": "string", "description": "Indicate the type of user: owner user, teammate admin user, or normal teammate", "enum": [ "admin", "owner", "teammate" ] }, "is_admin": { "type": "boolean", "description": "Set to true if teammate has admin privileges" }, "phone": { "type": "string", "description": "(optional) Teammate's phone number" }, "website": { "type": "string", "description": "(optional) Teammate's website" }, "address": { "type": "string", "description": "(optional) Teammate's address" }, "address2": { "type": "string", "description": "(optional) Teammate's address" }, "city": { "type": "string", "description": "(optional) Teammate's city" }, "state": { "type": "string", "description": "(optional) Teammate's state" }, "zip": { "type": "string", "description": "(optional) Teammate's zip" }, "country": { "type": "string", "description": "(optional) Teammate's country" } } } } } }, "examples": { "application/json": { "results": [ { "username": "teammate1", "email": "teammate1@example.com", "first_name": "Jane", "last_name": "Doe", "user_type": "owner", "is_admin": true, "phone": "123-345-3453", "website": "www.example.com", "company": "ACME Inc.", "address": "123 Acme St", "address2": "", "city": "City", "state": "CA", "country": "USA", "zip": "12345" }, { "username": "teammate2", "email": "teammate2@example.com", "first_name": "John", "last_name": "Doe", "user_type": "teammate", "is_admin": false, "phone": "123-345-3453", "website": "www.example.com", "company": "ACME Inc.", "address": "123 Acme St", "address2": "", "city": "City", "state": "CA", "country": "USA", "zip": "12345" }, { "username": "teammate3", "email": "teammate3@example.com", "first_name": "Steve", "last_name": "Doe", "user_type": "admin", "is_admin": true, "phone": "123-345-3453", "website": "www.example.com", "company": "ACME Inc.", "address": "123 Acme St", "address2": "", "city": "City", "state": "CA", "country": "USA", "zip": "12345" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/teammates/pending/{token}/resend": { "parameters": [ { "name": "token", "in": "path", "description": "The token for the invite that you want to resend.", "required": true, "type": "string" } ], "post": { "operationId": "POST_v3-teammates-pending-token-resend", "summary": "Resend teammate invite", "tags": [ "Teammates" ], "description": "**This endpoint allows you to resend a Teammate invitation.**\n\nTeammate invitations will expire after 7 days. Resending an invitation will reset the expiration date.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "ID to identify invite" }, "email": { "type": "string", "description": "Teammate's email address" }, "scopes": { "type": "array", "description": "Initial set of permissions to give to teammate if they accept the invite", "items": { "type": "string" } }, "is_admin": { "type": "boolean", "description": "Set to true if teammate should have admin privileges" } } }, "examples": { "application/json": { "pending_id": "abc123abc", "email": "teammate1@example.com", "scopes": [ "user.profile.read", "user.profile.update" ], "is_admin": false } } }, "404": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "application/json": { "errors": [ { "message": "invalid pending key", "field": "pending_key" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/scopes/requests": { "get": { "operationId": "GET_v3-scopes-requests", "summary": "Retrieve access requests", "tags": [ "Teammates" ], "description": "**This endpoint allows you to retrieve a list of all recent access requests.**\n\nThe Response Header's `link` parameter will include pagination info.", "parameters": [ { "name": "limit", "in": "query", "description": "Optional field to limit the number of results returned.", "type": "integer", "default": 50 }, { "name": "offset", "in": "query", "description": "Optional beginning point in the list to retrieve from.", "type": "integer", "default": 0 } ], "responses": { "200": { "description": "", "schema": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer", "description": "Request ID" }, "scope_group_name": { "type": "string", "description": "Name of group of scopes associated to page teammate is requesting access to" }, "username": { "type": "string", "description": "Teammate's username" }, "email": { "type": "string", "description": "Teammate's email" }, "first_name": { "type": "string", "description": "Teammate's first name" }, "last_name": { "type": "string", "description": "Teammate's last name" } } } }, "examples": { "application/json": [ { "id": 1, "scope_group_name": "Mail Settings", "username": "teammate1", "email": "teammate1@example.com", "first_name": "Teammate", "last_name": "One" }, { "id": 2, "scope_group_name": "Stats", "username": "teammate2", "email": "teammate2@example.com", "first_name": "Teammate", "last_name": "Two" } ] } } }, "security": [ { "Authorization": [] } ] } }, "/teammates/pending": { "get": { "operationId": "GET_v3-teammates-pending", "summary": "Retrieve all pending teammates", "tags": [ "Teammates" ], "description": "**This endpoint allows you to retrieve a list of all pending Teammate invitations.**\n\nEach teammate invitation is valid for 7 days. Users may resend the invitation to refresh the expiration date.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "type": "object", "properties": { "email": { "type": "string", "description": "Email address teammate invite will be sent to" }, "scopes": { "type": "array", "description": "List of permissions to give teammate if they accept", "items": { "type": "string" } }, "is_admin": { "type": "boolean", "description": "Set to true to indicate teammate should have the same set of permissions as parent user" }, "token": { "type": "string", "description": "Invitation token used to identify user" }, "expiration_date": { "type": "integer", "description": "timestamp indicates when invite will expire. Expiration is 7 days after invite creation" } } } } } }, "examples": { "application/json": { "result": [ { "email": "user1@example.com", "scopes": [ "user.profile.read", "user.profile.edit" ], "is_admin": false, "pending_id": "abcd123abc", "expiration_date": 1456424263 }, { "email": "user2@example.com", "scopes": [], "is_admin": true, "pending_id": "bcde234bcd", "expiration_date": 1456424263 } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/teammates/{username}": { "parameters": [ { "name": "username", "in": "path", "description": "The username of the teammate that you want to retrieve.", "required": true, "type": "string" } ], "get": { "operationId": "GET_v3-teammates-username", "summary": "Retrieve specific teammate", "tags": [ "Teammates" ], "description": "**This endpoint allows you to retrieve a specific Teammate by username.**\n\nYou can retrieve the username's for each of your Teammates using the \"Retrieve all Teammates\" endpoint.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "Teammate's username" }, "first_name": { "type": "string", "description": "Teammate's first name" }, "last_name": { "type": "string", "description": "Teammate's last name" }, "email": { "type": "string", "description": "Teammate's email" }, "scopes": { "type": "array", "description": "Scopes associated to teammate", "items": {} }, "user_type": { "type": "string", "description": "Indicate the type of user: account owner, teammate admin user, or normal teammate", "enum": [ "admin", "owner", "teammate" ] }, "is_admin": { "type": "boolean", "description": "Set to true if teammate has admin privileges" }, "phone": { "type": "string", "description": "(optional) Teammate's phone number" }, "website": { "type": "string", "description": "(optional) Teammate's website" }, "address": { "type": "string", "description": "(optional) Teammate's address" }, "address2": { "type": "string", "description": "(optional) Teammate's address" }, "city": { "type": "string", "description": "(optional) Teammate's city" }, "state": { "type": "string", "description": "(optional) Teammate's state" }, "zip": { "type": "string", "description": "(optional) Teammate's zip" }, "country": { "type": "string", "description": "(optional) Teammate's country" } } }, "examples": { "application/json": { "username": "teammate1", "first_name": "Jane", "last_name": "Doe", "email": "teammate1@example.com", "scopes": [ "user.profile.read", "user.profile.update", "..." ], "user_type": "admin", "is_admin": true, "phone": "123-345-3453", "website": "www.example.com", "company": "ACME Inc.", "address": "123 Acme St", "address2": "", "city": "City", "state": "CA", "country": "USA", "zip": "12345" } } } }, "security": [ { "Authorization": [] } ] }, "patch": { "operationId": "PATCH_v3-teammates-username", "summary": "Update teammate's permissions", "tags": [ "Teammates" ], "description": "**This endpoint allows you to update a teammate’s permissions.**\n\nTo turn a teammate into an admin, the request body should contain an `is_admin` set to `true`. Otherwise, set `is_admin` to `false` and pass in all the scopes that a teammate should have.\n\n**Only the parent user or other admin teammates can update another teammate’s permissions.**\n\n**Admin users can only update permissions.**", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "scopes": { "type": "array", "description": "Provide list of scopes that should be given to teammate. If specifying list of scopes, is_admin should be set to False.", "items": { "type": "string" } }, "is_admin": { "type": "boolean", "description": "Set to True if this teammate should be promoted to an admin user. If True, scopes should be an empty array." } }, "required": [ "scopes", "is_admin" ], "example": { "scopes": [ "user.profile.read", "user.profile.edit" ], "is_admin": false } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "Teammate's username" }, "first_name": { "type": "string", "description": "Teammate's first name" }, "last_name": { "type": "string", "description": "Teammate's last name" }, "email": { "type": "string", "description": "Teammate's email address" }, "scopes": { "type": "array", "description": "Scopes given to teammate", "items": { "type": "string" } }, "user_type": { "type": "string", "description": "Indicate the type of user: owner user, teammate admin user, or normal teammate", "enum": [ "admin", "owner", "teammate" ] }, "is_admin": { "type": "boolean", "description": "Set to true if teammate has admin priveleges" }, "phone": { "type": "string", "description": "(optional) Teammate's phone number" }, "website": { "type": "string", "description": "(optional) Teammate's website" }, "address": { "type": "string", "description": "(optional) Teammate's address" }, "address2": { "type": "string", "description": "(optional) Teammate's address" }, "city": { "type": "string", "description": "(optional) Teammate's city" }, "state": { "type": "string", "description": "(optional) Teammate's state" }, "zip": { "type": "string", "description": "(optional) Teammate's zip" }, "country": { "type": "string", "description": "(optional) Teammate's country" } } }, "examples": { "application/json": { "username": "teammate1", "first_name": "Jane", "last_name": "Doe", "email": "teammate1@example.com", "scopes": [ "user.profile.read", "user.profile.edit" ], "user_type": "teammate", "is_admin": false, "phone": "123-345-3453", "website": "www.example.com", "company": "ACME Inc.", "address": "123 Acme St", "address2": "", "city": "City", "state": "CA", "country": "USA", "zip": "12345" } } }, "400": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "application/json": { "errors": [ { "message": "one or more of given scopes are invalid", "field": "scopes" } ] } } }, "404": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "application/json": { "errors": [ { "message": "username not found", "field": "username" } ] } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_v3-teammates-username", "summary": "Delete teammate", "tags": [ "Teammates" ], "description": "**This endpoint allows you to delete a teammate.**\n\n**Only the parent user or an admin teammate can delete another teammate.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "204": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } } }, "404": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "application/json": { "errors": [ { "message": "username not found", "field": "username" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/scopes/requests/{request_id}/approve": { "parameters": [ { "name": "request_id", "in": "path", "description": "The ID of the request that you want to approve.", "required": true, "type": "string" } ], "patch": { "operationId": "PATCH_v3-scopes-requests-approve-id", "summary": "Approve access request", "tags": [ "Teammates" ], "description": "**This endpoint allows you to approve an access attempt.**\n\n**Note:** Only teammate admins may approve another teammate’s access request.", "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "scope_group_name": { "type": "string", "description": "name of feature teammate will be given access to" } } }, "examples": { "application/json": { "scope_group_name": "Stats" } } }, "401": { "description": "", "schema": { "type": "object" } }, "404": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } } } }, "security": [ { "Authorization": [] } ] } }, "/scopes/requests/{request_id}": { "parameters": [ { "name": "request_id", "in": "path", "description": "The ID of the request that you want to deny.", "required": true, "type": "string" } ], "delete": { "operationId": "DELETE_v3-scopes-requests-request_id", "summary": "Deny access request", "tags": [ "Teammates" ], "description": "**This endpoint allows you to deny an attempt to access your account.**\n\n**Note:** Only teammate admins may delete a teammate's access request.", "responses": { "204": { "description": "" }, "401": { "description": "" }, "404": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } }, "examples": { "application/json": { "errors": [ { "message": "Cannot find request", "field": "request_id" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/teammates/pending/{token}": { "parameters": [ { "name": "token", "in": "path", "description": "The token for the invite you want to delete.", "required": true, "type": "string" } ], "delete": { "operationId": "DELETE_v3-teammates-pending-token", "summary": "Delete pending teammate", "tags": [ "Teammates" ], "description": "**This endpoint allows you to delete a pending teammate invite.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "204": { "description": "" }, "404": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "field": { "type": "string" } } } } } } } }, "security": [ { "Authorization": [] } ] } }, "/alerts": { "post": { "operationId": "POST_alerts", "summary": "Create a new Alert", "tags": [ "Alerts" ], "description": "**This endpoint allows you to create a new alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. There are two types of alerts that can be created with this endpoint:\n\n* `usage_limit` allows you to set the threshold at which an alert will be sent.\n* `stats_notification` allows you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of alert you want to create. Can be either usage_limit or stats_notification.\nExample: usage_limit", "enum": [ "stats_notification", "usage_limit" ] }, "email_to": { "type": "string", "description": "The email address the alert will be sent to.\nExample: test@example.com", "format": "email", "nullable": true }, "frequency": { "type": "string", "description": "Required for stats_notification. How frequently the alert will be sent.\nExample: daily" }, "percentage": { "type": "integer", "description": "Required for usage_alert. When this usage threshold is reached, the alert will be sent.\nExample: 90" } }, "required": [ "type", "email_to" ], "example": { "type": "stats_notification", "email_to": "example@example.com", "frequency": "daily" } } }, { "name": "Authorization", "in": "header", "type": "string" }, { "name": "on-behalf-of", "in": "header", "type": "string" } ], "responses": { "201": { "description": "", "schema": { "type": "object", "properties": { "created_at": { "type": "integer", "description": "A Unix timestamp indicating when the alert was created." }, "email_to": { "type": "string", "description": "The email address that the alert will be sent to.", "format": "email" }, "frequency": { "type": "string", "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, \"daily\", \"weekly\", or \"monthly\"." }, "id": { "type": "integer", "description": "The ID of the alert." }, "type": { "type": "string", "description": "The type of alert." }, "updated_at": { "type": "integer", "description": "A Unix timestamp indicating when the alert was last modified." }, "percentage": { "type": "integer", "description": "\"If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent." } }, "required": [ "created_at", "email_to", "id", "type", "updated_at" ] }, "examples": { "application/json": { "created_at": 1451520930, "email_to": "test@example.com", "frequency": "daily", "id": 48, "type": "stats_notification", "updated_at": 1451520930 } } }, "400": { "description": "", "schema": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_alerts", "summary": "Retrieve all alerts", "tags": [ "Alerts" ], "description": "**This endpoint allows you to retrieve all of your alerts.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).", "parameters": [ { "name": "Authorization", "in": "header", "type": "string" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "array", "description": "The list of alerts.", "items": { "type": "object", "properties": { "created_at": { "type": "integer", "description": "A Unix timestamp indicating when the alert was created." }, "email_to": { "type": "string", "description": "The email address that the alert will be sent to." }, "id": { "type": "integer", "description": "The ID of the alert." }, "percentage": { "type": "integer", "description": "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent." }, "type": { "type": "string", "description": "The type of alert.", "enum": [ "usage_limit", "stats_notification" ] }, "updated_at": { "type": "integer", "description": "A Unix timestamp indicating when the alert was last modified." }, "frequency": { "type": "string", "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example, \"daily\", \"weekly\", or \"monthly\"." } }, "required": [ "created_at", "email_to", "id", "type" ] } }, "examples": { "application/json": [ { "created_at": 1451498784, "email_to": "example1@example.com", "id": 46, "percentage": 90, "type": "usage_limit", "updated_at": 1451498784 }, { "created_at": 1451498812, "email_to": "example2@example.com", "frequency": "monthly", "id": 47, "type": "stats_notification", "updated_at": 1451498812 }, { "created_at": 1451520930, "email_to": "example3@example.com", "frequency": "daily", "id": 48, "type": "stats_notification", "updated_at": 1451520930 } ] } } }, "security": [ { "Authorization": [] } ] } }, "/alerts/{alert_id}": { "parameters": [ { "name": "alert_id", "in": "path", "description": "The ID of the alert you would like to retrieve.", "required": true, "type": "integer" } ], "get": { "operationId": "GET_alerts-alert_id", "summary": "Retrieve a specific alert", "tags": [ "Alerts" ], "description": "**This endpoint allows you to retrieve a specific alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).", "parameters": [ { "name": "Authorization", "in": "header", "type": "string" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "created_at": { "type": "integer", "description": "A Unix timestamp indicating when the alert was created." }, "email_to": { "type": "string", "description": "The email address that the alert will be sent to." }, "frequency": { "type": "string", "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: \"daily\", \"weekly\", or \"monthly\"." }, "id": { "type": "integer", "description": "The ID of the alert." }, "type": { "type": "string", "description": "The type of alert.", "enum": [ "usage_alert", "stats_notification" ] }, "updated_at": { "type": "integer", "description": "A Unix timestamp indicating when the alert was last modified." }, "percentage": { "type": "integer", "description": "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent." } }, "required": [ "created_at", "email_to", "id", "type", "updated_at" ] }, "examples": { "application/json": { "created_at": 1451520930, "email_to": "example@example.com", "frequency": "daily", "id": 48, "type": "stats_notification", "updated_at": 1451520930 } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_alerts-alert_id", "summary": "Delete an alert", "tags": [ "Alerts" ], "description": "**This endpoint allows you to delete an alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "204": { "description": "", "schema": { "type": "object", "properties": {} } } }, "security": [ { "Authorization": [] } ] }, "patch": { "operationId": "PATCH_alerts-alert_id", "summary": "Update an alert", "tags": [ "Alerts" ], "description": "**This endpoint allows you to update an alert.**\n\nAlerts allow you to specify an email address to receive notifications regarding your email usage or statistics. \n* Usage alerts allow you to set the threshold at which an alert will be sent.\n* Stats notifications allow you to set how frequently you would like to receive email statistics reports. For example, \"daily\", \"weekly\", or \"monthly\".\n\nFor more information about alerts, please see our [Alerts documentation](https://sendgrid.com/docs/ui/account-and-settings/alerts/).", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "email_to": { "type": "string", "description": "The new email address you want your alert to be sent to.\nExample: test@example.com" }, "frequency": { "type": "string", "description": "The new frequency at which to send the stats_notification alert.\nExample: monthly" }, "percentage": { "type": "integer", "description": "The new percentage threshold at which the usage_limit alert will be sent.\nExample: 90" } }, "example": { "email_to": "example@example.com" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "created_at": { "type": "integer", "description": "A Unix timestamp indicating when the alert was created." }, "email_to": { "type": "string", "description": "The email address that the alert will be sent to." }, "frequency": { "type": "string", "description": "If the alert is of type stats_notification, this indicates how frequently the stats notifications will be sent. For example: \"daily\", \"weekly\", or \"monthly\"." }, "id": { "type": "integer", "description": "The ID of the alert." }, "type": { "type": "string", "description": "The type of alert.", "enum": [ "usage_alert", "stats_notification" ] }, "updated_at": { "type": "integer", "description": "A Unix timestamp indicating when the alert was last modified." }, "percentage": { "type": "integer", "description": "If the alert is of type usage_limit, this indicates the percentage of email usage that must be reached before the alert will be sent." } }, "required": [ "created_at", "email_to", "id", "type", "updated_at" ] }, "examples": { "application/json": { "created_at": 1451520930, "email_to": "example@example.com", "frequency": "daily", "id": 48, "type": "stats_notification", "updated_at": 1451522691 } } } }, "security": [ { "Authorization": [] } ] } }, "/user/profile": { "get": { "operationId": "GET_user-profile", "summary": "Get a user's profile", "tags": [ "Users API" ], "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "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": { "application/json": { "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" } } } }, "security": [ { "Authorization": [] } ] }, "patch": { "operationId": "PATCH_user-profile", "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": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/user_profile", "example": { "first_name": "Example", "last_name": "User", "city": "Orange" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/user_profile" }, "examples": { "application/json": { "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": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/user/account": { "get": { "operationId": "GET_user-account", "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": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "title": "GET User Account response", "type": "object", "properties": { "type": { "type": "string", "description": "The type of account for this user.", "enum": [ "free", "paid" ] }, "reputation": { "type": "number", "description": "The sender reputation for this user." } }, "required": [ "type", "reputation" ] }, "examples": { "application/json": { "reputation": 100, "type": "paid" } } } }, "security": [ { "Authorization": [] } ] } }, "/user/email": { "get": { "operationId": "GET_user-email", "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": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address currently on file for your account.", "format": "email" } }, "required": [ "email" ] }, "examples": { "application/json": { "email": "test@example.com" } } } }, "security": [ { "Authorization": [] } ] }, "put": { "operationId": "PUT_user-email", "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": [ { "name": "body", "in": "body", "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" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The current email address on file for your account.", "format": "email" } }, "required": [ "email" ] }, "examples": { "application/json": { "email": "example@example.com" } } } }, "security": [ { "Authorization": [] } ] } }, "/user/username": { "get": { "operationId": "GET_user-username", "summary": "Retrieve your username", "tags": [ "Users API" ], "description": "**This endpoint allows you to retrieve your current account username.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "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": { "application/json": { "username": "test_username", "user_id": 1 } } } }, "security": [ { "Authorization": [] } ] }, "put": { "operationId": "PUT_user-username", "summary": "Update your username", "tags": [ "Users API" ], "description": "**This endpoint allows you to update the username for your account.**", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "The new username you would like to use for your account." } }, "example": { "username": "test_username" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "The current username on file for your account." } }, "required": [ "username" ] }, "examples": { "application/json": { "username": "test_username" } } } }, "security": [ { "Authorization": [] } ] } }, "/user/credits": { "get": { "operationId": "GET_user-credits", "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": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "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": { "application/json": { "remain": 200, "total": 200, "overage": 0, "used": 0, "last_reset": "2013-01-01", "next_reset": "2013-02-01", "reset_frequency": "monthly" } } } }, "security": [ { "Authorization": [] } ] } }, "/user/password": { "put": { "operationId": "PUT_user-password", "summary": "Update your password", "tags": [ "Users API" ], "description": "**This endpoint allows you to update your password.**", "parameters": [ { "name": "body", "in": "body", "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" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": {} } } }, "security": [ { "Authorization": [] } ] } }, "/subusers": { "get": { "operationId": "GET_subusers", "summary": "List all Subusers", "tags": [ "Subusers API" ], "description": "**This endpoint allows you to retrieve a list of all of your subusers.**\n\nYou can choose to retrieve specific subusers as well as limit the results that come back from the API.", "parameters": [ { "name": "username", "in": "query", "description": "The username of this subuser.", "type": "string" }, { "name": "limit", "in": "query", "description": "The number of results you would like to get in each request.", "type": "integer" }, { "name": "offset", "in": "query", "description": "The number of subusers to skip.", "type": "integer" } ], "responses": { "200": { "description": "", "schema": { "type": "array", "items": { "$ref": "#/definitions/subuser" } }, "examples": { "application/json": [ { "disabled": false, "email": "example@example.com", "id": 1234, "username": "example_subuser" }, { "disabled": false, "email": "example2@example.com", "id": 1234, "username": "example_subuser2" } ] } }, "401": { "description": "Unexpected error in API call. See HTTP response body for details.", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } } }, "security": [ { "Authorization": [] } ] }, "post": { "operationId": "POST_subusers", "summary": "Create Subuser", "tags": [ "Subusers API" ], "description": "**This endpoint allows you to create a new subuser.**", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "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" } } }, "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" ] } } } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/subuser_post" }, "examples": { "application/json": { "username": "example_subuser", "user_id": 1234, "email": "example@example.com", "signup_session_token": "", "authorization_token": "", "credit_allocation": { "type": "unlimited" } } } }, "400": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "message": "username exists" }, { "message": "unable to validate IPs at this time" } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } }, "403": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "message": "you dont have permission to access this resource" } ] } } }, "500": { "description": "", "schema": { "type": "object" }, "examples": { "application/json": { "errors": [ { "message": "unable to validate IPs at this time" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/subusers/{subuser_name}": { "parameters": [ { "name": "subuser_name", "in": "path", "required": true, "type": "string" } ], "patch": { "operationId": "PATCH_subusers-subuser_name", "summary": "Enable/disable a subuser", "tags": [ "Subusers API" ], "description": "**This endpoint allows you to enable or disable a subuser.**", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "disabled": { "type": "boolean", "description": "Whether or not this subuser is disabled. True means disabled, False means enabled." } }, "example": { "disabled": false } } } ], "responses": { "204": { "description": "", "schema": { "type": "object", "properties": {} } }, "400": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "message": "invalid username" }, { "message": "no fields provided" } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } }, "500": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "message": "unable to enable user" } ] } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_subusers-subuser_name", "summary": "Delete a subuser", "tags": [ "Subusers API" ], "description": "**This endpoint allows you to delete a subuser.**\n\nThis is a permanent action. Once deleted, a subuser cannot be retrieved.", "responses": { "204": { "description": "", "schema": { "type": "object", "properties": {} } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/subusers/reputations": { "get": { "operationId": "GET_subusers-reputations", "summary": "Retrieve Subuser Reputations", "tags": [ "Subusers API" ], "description": "**This endpoint allows you to request the reputations for your subusers.**\n\nSubuser sender reputations give a good idea how well a sender is doing with regards to how recipients and recipient servers react to the mail that is being received. When a bounce, spam report, or other negative action happens on a sent email, it will affect your sender rating.", "parameters": [ { "name": "usernames", "in": "query", "type": "string" } ], "responses": { "200": { "description": "", "schema": { "type": "array", "items": { "type": "object", "properties": { "reputation": { "type": "number", "description": "The sender reputation this subuser has attained." }, "username": { "type": "string", "description": "The subuser that has this reputation.f" } }, "required": [ "reputation", "username" ] } }, "examples": { "application/json": [ { "username": "example_subuser", "reputation": 99 }, { "username": "example_subuser2", "reputation": 95.2 } ] } } }, "security": [ { "Authorization": [] } ] } }, "/subusers/{subuser_name}/ips": { "parameters": [ { "name": "subuser_name", "in": "path", "required": true, "type": "string" } ], "put": { "operationId": "PUT_subusers-subuser_name-ips", "summary": "Update IPs assigned to a subuser", "tags": [ "Subusers API" ], "description": "**This endpoint allows you update your subusers' assigned IP.**\n\nEach subuser should be assigned to an IP address from which all of this subuser's mail will be sent. Often, this is the same IP as the parent account, but each subuser can have one or more of their own IP addresses as well. \n\nMore information:\n\n* [How to request more IPs](https://sendgrid.com/docs/ui/account-and-settings/dedicated-ip-addresses/)\n* [Setup Reverse DNS](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-reverse-dns/)", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "array", "description": "The IP addresses you would like to assign to the subuser.", "items": { "type": "string", "format": "ipv4" }, "example": [ "127.0.0.1" ] } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "ips": { "type": "array", "description": "The IP addresses that are assigned to the subuser.", "items": { "type": "string", "format": "ipv4" } } } }, "examples": { "application/json": { "ips": [ "127.0.0.1" ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/subusers/{subuser_name}/monitor": { "parameters": [ { "name": "subuser_name", "in": "path", "description": "The name of the subuser for which to retrieve monitor settings.", "required": true, "type": "string" } ], "get": { "operationId": "GET_subusers-subuser_name-monitor", "summary": "Retrieve monitor settings for a subuser", "tags": [ "Subuser Monitor Settings" ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/monitor" }, "examples": { "application/json": { "email": "example@example.com", "frequency": 500 } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } }, "404": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "No monitor settings for this user" } ] } } } }, "security": [ { "Authorization": [] } ] }, "post": { "operationId": "POST_subusers-subuser_name-monitor", "summary": "Create monitor settings", "tags": [ "Subuser Monitor Settings" ], "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/monitor", "example": { "email": "example@example.com", "frequency": 50000 } } } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/monitor" }, "examples": { "application/json": { "email": "example@example.com", "frequency": 50000 } } }, "400": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "User already has a monitor" } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } } }, "security": [ { "Authorization": [] } ] }, "put": { "operationId": "PUT_subusers-subuser_name-monitor", "summary": "Update Monitor Settings for a subuser", "tags": [ "Subuser Monitor Settings" ], "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/monitor", "example": { "email": "example@example.com", "frequency": 500 } } } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/monitor" }, "examples": { "application/json": { "email": "example@example.com", "frequency": 500 } } }, "400": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": "email", "message": "Email is required" } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_subusers-subuser_name-monitor", "summary": "Delete monitor settings", "tags": [ "Subuser Monitor Settings" ], "responses": { "204": { "description": "", "schema": { "type": "object", "properties": {} } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } }, "404": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "No monitor settings for this user" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/subusers/{subuser_name}/stats/monthly": { "parameters": [ { "name": "subuser_name", "in": "path", "required": true, "type": "string" } ], "get": { "operationId": "GET_subusers-subuser_name-stats-monthly", "summary": "Retrieve the monthly email statistics for a single subuser", "tags": [ "Subuser Statistics" ], "description": "**This endpoint allows you to retrive the monthly email statistics for a specific subuser.**\n\nWhen using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics:\n`bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`.", "parameters": [ { "name": "date", "in": "query", "description": "The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD", "required": true, "type": "string" }, { "name": "sort_by_metric", "in": "query", "description": "The metric that you want to sort by. Metrics that you can sort by are: `blocks`, `bounces`, `clicks`, `delivered`, `opens`, `requests`, `unique_clicks`, `unique_opens`, and `unsubscribes`.'", "required": false, "type": "string", "default": "delivered" }, { "name": "sort_by_direction", "in": "query", "description": "The direction you want to sort.", "required": false, "type": "string", "default": "desc", "enum": [ "desc", "asc" ] }, { "name": "limit", "in": "query", "description": "Optional field to limit the number of results returned.", "required": false, "type": "integer", "default": 5 }, { "name": "offset", "in": "query", "description": "Optional beginning point in the list to retrieve from.", "required": false, "type": "integer", "default": 0 } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/subuser_stats" }, "examples": { "application/json": { "date": "2016-02-01", "stats": [ { "first_name": "John", "last_name": "Doe", "metrics": { "blocks": 0, "bounce_drops": 0, "bounces": 0, "clicks": 5, "deferred": 0, "delivered": 0, "invalid_emails": 0, "opens": 10, "processed": 10, "requests": 10, "spam_report_drops": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0, "unsubscribe_drops": 0, "unsubscribes": 0 }, "name": "user1", "type": "subuser" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/subusers/stats/monthly": { "get": { "operationId": "GET_subusers-stats-monthly", "summary": "Retrieve monthly stats for all subusers", "tags": [ "Subuser Statistics" ], "description": "**This endpoint allows you to retrieve the monthly email statistics for all subusers over the given date range.**\n\nWhen using the `sort_by_metric` to sort your stats by a specific metric, you can not sort by the following metrics:\n`bounce_drops`, `deferred`, `invalid_emails`, `processed`, `spam_report_drops`, `spam_reports`, or `unsubscribe_drops`.", "parameters": [ { "name": "date", "in": "query", "description": "The date of the month to retrieve statistics for. Must be formatted YYYY-MM-DD", "required": true, "type": "string" }, { "name": "subuser", "in": "query", "description": "A substring search of your subusers.", "required": false, "type": "string" }, { "name": "sort_by_metric", "in": "query", "description": "The metric that you want to sort by. Metrics that you can sort by are: `blocks`, `bounces`, `clicks`, `delivered`, `opens`, `requests`, `unique_clicks`, `unique_opens`, and `unsubscribes`.'", "required": false, "type": "string", "default": "delivered", "enum": [ "blocks", "bounces", "clicks", "delivered", "opens", "requests", "unique_clicks", "unique_opens", "unsubscribes" ] }, { "name": "sort_by_direction", "in": "query", "description": "The direction you want to sort.", "required": false, "type": "string", "default": "desc", "enum": [ "desc", "asc" ] }, { "name": "limit", "in": "query", "description": "Optional field to limit the number of results returned.", "required": false, "type": "integer", "default": 5 }, { "name": "offset", "in": "query", "description": "Optional beginning point in the list to retrieve from.", "required": false, "type": "integer", "default": 0 } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/subuser_stats" }, "examples": { "application/json": { "date": "2016-02-01", "stats": [ { "first_name": "John", "last_name": "Doe", "metrics": { "blocks": 0, "bounce_drops": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "invalid_emails": 0, "opens": 1, "processed": 0, "requests": 100, "spam_report_drops": 0, "spam_reports": 99, "unique_clicks": 0, "unique_opens": 0, "unsubscribe_drops": 0, "unsubscribes": 0 }, "name": "user1", "type": "subuser" }, { "first_name": "Jane", "last_name": "Doe", "metrics": { "blocks": 0, "bounce_drops": 0, "bounces": 0, "clicks": 5, "deferred": 0, "delivered": 0, "invalid_emails": 0, "opens": 10, "processed": 10, "requests": 10, "spam_report_drops": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0, "unsubscribe_drops": 0, "unsubscribes": 0 }, "name": "user2", "type": "subuser" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/subusers/stats/sums": { "get": { "operationId": "GET_subusers-stats-sums", "summary": "Retrieve the totals for each email statistic metric for all subusers.", "tags": [ "Subuser Statistics" ], "description": "**This endpoint allows you to retrieve the total sums of each email statistic metric for all subusers over the given date range.**", "parameters": [ { "name": "sort_by_direction", "in": "query", "description": "The direction you want to sort. ", "required": false, "type": "string", "default": "desc", "enum": [ "desc", "asc" ] }, { "name": "start_date", "in": "query", "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "The end date of the statistics to retrieve. Defaults to today. Must follow format YYYY-MM-DD.", "required": false, "type": "string" }, { "name": "limit", "in": "query", "description": "Limits the number of results returned per page.", "required": false, "type": "integer", "default": 5 }, { "name": "offset", "in": "query", "description": "The point in the list to begin retrieving results from.", "required": false, "type": "integer", "default": 0 }, { "name": "aggregated_by", "in": "query", "description": "How to group the statistics. Defaults to today. Must follow format YYYY-MM-DD.", "required": false, "type": "string" }, { "name": "sort_by_metric", "in": "query", "description": "The metric that you want to sort by. Must be a single metric.", "required": false, "type": "string", "default": "delivered" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/category_stats" }, "examples": { "application/json": { "date": "2015-10-11", "stats": [] } } } }, "security": [ { "Authorization": [] } ] } }, "/subusers/stats": { "get": { "operationId": "GET_subusers-stats", "summary": "Retrieve email statistics for your subusers.", "tags": [ "Subuser Statistics" ], "description": "**This endpoint allows you to retrieve the email statistics for the given subusers.**\n\nYou may retrieve statistics for up to 10 different subusers by including an additional _subusers_ parameter for each additional subuser.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of results returned per page.", "required": false, "type": "integer" }, { "name": "offset", "in": "query", "description": "The point in the list to begin retrieving results from.", "required": false, "type": "integer" }, { "name": "aggregated_by", "in": "query", "description": "How to group the statistics. Must be either \"day\", \"week\", or \"month\".", "required": false, "type": "string", "enum": [ "day", "week", "month" ] }, { "name": "subusers", "in": "query", "description": "The subuser you want to retrieve statistics for. You may include this parameter up to 10 times to retrieve statistics for multiple subusers.", "required": true, "type": "string" }, { "name": "start_date", "in": "query", "description": "The starting date of the statistics to retrieve. Must follow format YYYY-MM-DD.", "required": true, "type": "string" }, { "name": "end_date", "in": "query", "description": "The end date of the statistics to retrieve. Defaults to today.", "required": false, "type": "string" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/category_stats" }, "examples": { "application/json": [ { "date": "2015-10-01", "stats": [ { "type": "subuser", "name": "Matt_subuser", "metrics": { "blocks": 0, "bounce_drops": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "invalid_emails": 0, "opens": 0, "processed": 0, "requests": 0, "spam_report_drops": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0, "unsubscribe_drops": 0, "unsubscribes": 0 } } ] }, { "date": "2015-10-02", "stats": [ { "type": "subuser", "name": "Matt_subuser", "metrics": { "blocks": 0, "bounce_drops": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "invalid_emails": 0, "opens": 0, "processed": 0, "requests": 0, "spam_report_drops": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0, "unsubscribe_drops": 0, "unsubscribes": 0 } } ] }, { "date": "2015-10-03", "stats": [ { "type": "subuser", "name": "Matt_subuser", "metrics": { "blocks": 0, "bounce_drops": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "invalid_emails": 0, "opens": 0, "processed": 0, "requests": 0, "spam_report_drops": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0, "unsubscribe_drops": 0, "unsubscribes": 0 } } ] }, { "date": "2015-10-04", "stats": [ { "type": "subuser", "name": "Matt_subuser", "metrics": { "blocks": 0, "bounce_drops": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "invalid_emails": 0, "opens": 0, "processed": 0, "requests": 0, "spam_report_drops": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0, "unsubscribe_drops": 0, "unsubscribes": 0 } } ] }, { "date": "2015-10-05", "stats": [ { "type": "subuser", "name": "Matt_subuser", "metrics": { "blocks": 0, "bounce_drops": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "invalid_emails": 0, "opens": 0, "processed": 0, "requests": 0, "spam_report_drops": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0, "unsubscribe_drops": 0, "unsubscribes": 0 } } ] }, { "date": "2015-10-06", "stats": [ { "type": "subuser", "name": "Matt_subuser", "metrics": { "blocks": 0, "bounce_drops": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "invalid_emails": 0, "opens": 0, "processed": 0, "requests": 0, "spam_report_drops": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0, "unsubscribe_drops": 0, "unsubscribes": 0 } } ] }, { "date": "2015-10-07", "stats": [ { "type": "subuser", "name": "Matt_subuser", "metrics": { "blocks": 0, "bounce_drops": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "invalid_emails": 0, "opens": 0, "processed": 0, "requests": 0, "spam_report_drops": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0, "unsubscribe_drops": 0, "unsubscribes": 0 } } ] }, { "date": "2015-10-08", "stats": [ { "type": "subuser", "name": "Matt_subuser", "metrics": { "blocks": 0, "bounce_drops": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "invalid_emails": 0, "opens": 0, "processed": 0, "requests": 0, "spam_report_drops": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0, "unsubscribe_drops": 0, "unsubscribes": 0 } } ] }, { "date": "2015-10-09", "stats": [ { "type": "subuser", "name": "Matt_subuser", "metrics": { "blocks": 0, "bounce_drops": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "invalid_emails": 0, "opens": 0, "processed": 0, "requests": 0, "spam_report_drops": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0, "unsubscribe_drops": 0, "unsubscribes": 0 } } ] }, { "date": "2015-10-10", "stats": [ { "type": "subuser", "name": "Matt_subuser", "metrics": { "blocks": 0, "bounce_drops": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "invalid_emails": 0, "opens": 0, "processed": 0, "requests": 0, "spam_report_drops": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0, "unsubscribe_drops": 0, "unsubscribes": 0 } } ] } ] } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/links": { "post": { "operationId": "POST_whitelabel-links", "summary": "Create a branded link", "tags": [ "Link branding" ], "description": "**This endpoint allows you to create a new branded link.**\n\nTo create the link branding, supply the root domain and, optionally, the subdomain — these go into separate fields in your request body. The root domain should match your FROM email address. If you provide a subdomain, it must be different from the subdomain you used for authenticating your domain.\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "The root domain for the subdomain that you are creating the link branding for. This should match your FROM email address." }, "subdomain": { "type": "string", "description": "The subdomain to create the link branding for. Must be different from the subdomain you used for authenticating your domain." }, "default": { "type": "boolean", "description": "Indicates if you want to use this link branding as the default or fallback. When setting a new default, the existing default link branding will have its default status removed automatically.", "enum": [ true, false ] } }, "required": [ "domain" ], "example": { "domain": "example.com", "subdomain": "mail", "default": true } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "201": { "description": "", "schema": { "$ref": "#/definitions/link_branding_200_response" }, "examples": { "application/json": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "john@example.com", "user_id": 7, "default": false, "valid": true, "legacy": false, "dns": { "domain_cname": { "valid": true, "type": "cname", "host": "mail.example.com", "data": "sendgrid.net" }, "owner_cname": { "valid": true, "type": "cname", "host": "7.example.com", "data": "sendgrid.net" } } } } } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_whitelabel-links", "summary": "Retrieve all branded links", "tags": [ "Link branding" ], "description": "**This endpoint allows you to retrieve all branded links**.\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", "parameters": [ { "name": "limit", "in": "query", "description": "Limits the number of results returned per page.", "type": "integer" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "array", "items": { "$ref": "#/definitions/link_branding_200_response" } }, "examples": { "application/json": [ { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "john@example.com", "user_id": 7, "default": true, "valid": true, "legacy": false, "dns": { "domain_cname": { "valid": true, "type": "cname", "host": "mail.example.com", "data": "sendgrid.net" }, "owner_cname": { "valid": true, "type": "cname", "host": "7.example.com", "data": "sendgrid.net" } } }, { "id": 2, "domain": "example2.com", "subdomain": "news", "username": "john@example.com", "user_id": 8, "default": false, "valid": false, "legacy": false, "dns": { "domain_cname": { "valid": true, "type": "cname", "host": "news.example2.com", "data": "sendgrid.net" }, "owner_cname": { "valid": false, "type": "cname", "host": "8.example2.com", "data": "sendgrid.net" } } } ] } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/links/{id}/validate": { "parameters": [ { "name": "id", "in": "path", "description": "The ID of the branded link that you want to validate.", "required": true, "type": "integer" } ], "post": { "operationId": "POST_whitelabel-links-id-validate", "summary": "Validate a branded link", "tags": [ "Link branding" ], "description": "**This endpoint allows you to validate a branded link.**\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the branded link." }, "valid": { "type": "boolean", "description": "Indicates if the link branding is valid.", "enum": [ true, false ] }, "validation_results": { "type": "object", "description": "The individual validation results for each of the DNS records associated with this branded link.", "required": [ "domain_cname" ], "properties": { "domain_cname": { "type": "object", "description": "The DNS record generated for the sending domain used for this branded link.", "required": [ "valid", "reason" ], "properties": { "valid": { "type": "boolean", "description": "Indicates if this DNS record is valid.", "enum": [ true, false ] }, "reason": { "type": "string", "nullable": true, "description": "Null if the DNS record is valid. If the DNS record is invalid, this will explain why." } } }, "owner_cname": { "type": "object", "description": "The DNS record created to verify the branded link.", "properties": { "valid": { "type": "boolean", "description": "Indicates if the DNS record is valid.", "enum": [ true, false ] }, "reason": { "type": "string", "nullable": true, "description": "Null if valid. If the DNS record is invalid, this will explain why." } }, "required": [ "valid", "reason" ] } } } }, "required": [ "id", "valid", "validation_results" ] }, "examples": { "application/json": { "id": 1, "valid": true, "validation_results": { "domain_cname": { "valid": false, "reason": "Expected CNAME to match \"sendgrid.net.\" but found \"example.com.\"." }, "owner_cname": { "valid": true, "reason": null } } } } }, "500": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "description": "The reasons why the validation failed.", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "The reason why the link whitelabel could not be validated." } }, "required": [ "message" ] } } }, "required": [ "errors" ] }, "examples": { "application/json": { "errors": [ { "message": "internal error getting CNAME" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/links/{link_id}/subuser": { "parameters": [ { "name": "link_id", "in": "path", "description": "The ID of the branded link you want to associate.", "required": true, "type": "integer" } ], "post": { "operationId": "POST_whitelabel-links-link_id-subuser", "summary": "Associate a branded link with a subuser", "tags": [ "Link branding" ], "description": "**This endpoint allows you to associate a branded link with a subuser account.**\n\nLink branding can be associated with subusers from the parent account. This functionality allows subusers to send mail using their parent's link branding. To associate link branding, the parent account must first create a branded link and validate it. The parent may then associate that branded link with a subuser via the API or the [Subuser Management page of the Twilio SendGrid App](https://app.sendgrid.com/settings/subusers).", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "The username of the subuser account that you want to associate the branded link with." } }, "example": { "username": "jane@example.com" } } } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/link_branding_200_response" }, "examples": { "application/json": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "john@example.com", "user_id": 7, "default": false, "valid": true, "legacy": false, "dns": { "domain_cname": { "valid": true, "type": "cname", "host": "mail.example.com", "data": "sendgrid.net" }, "owner_cname": { "valid": true, "type": "cname", "host": "7.example.com", "data": "sendgrid.net" } } } } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/links/{id}": { "parameters": [ { "name": "id", "in": "path", "description": "The ID of the branded link you want to retrieve.", "required": true, "type": "integer" } ], "get": { "operationId": "GET_whitelabel-links-id", "summary": "Retrieve a branded link", "tags": [ "Link branding" ], "description": "**This endpoint allows you to retrieve a specific branded link by providing its ID.**\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/link_branding_200_response" }, "examples": { "application/json": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "john@example.com", "user_id": 7, "default": false, "valid": true, "legacy": false, "dns": { "domain_cname": { "valid": true, "type": "cname", "host": "mail.example.com", "data": "sendgrid.net" }, "owner_cname": { "valid": true, "type": "cname", "host": "7.example.com", "data": "sendgrid.net" } } } } } }, "security": [ { "Authorization": [] } ] }, "patch": { "operationId": "PATCH_whitelabel-links-id", "summary": "Update a branded link", "tags": [ "Link branding" ], "description": "**This endpoint allows you to update a specific branded link. You can use this endpoint to change a branded link's default status.**\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "default": { "type": "boolean", "description": "Indicates if the branded link is set as the default. When setting a new default, the existing default link branding will have its default status removed automatically.", "enum": [ true, false ] } }, "example": { "default": true } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/link_branding_200_response" }, "examples": { "application/json": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "john@example.com", "user_id": 7, "default": true, "valid": true, "legacy": false, "dns": { "domain_cname": { "valid": true, "type": "cname", "host": "mail.example.com", "data": "sendgrid.net" }, "owner_cname": { "valid": true, "type": "cname", "host": "7.example.com", "data": "sendgrid.net" } } } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_whitelabel-links-id", "summary": "Delete a branded link", "tags": [ "Link branding" ], "description": "**This endpoint allows you to delete a branded link.**\n\nYour request will receive a response with a 204 status code if the deletion was successful. The call does not return the link's details, so if you wish to record these make sure you call the \"Retrieve a branded link\" endpoint *before* you request its deletion.\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "204": { "description": "", "schema": { "type": "object" } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/links/default": { "get": { "operationId": "GET_whitelabel-links-default", "summary": "Retrieve the default branded link", "tags": [ "Link branding" ], "description": "**This endpoint allows you to retrieve the default branded link.**\n\nThe default branded link is the actual URL to be used when sending messages. If you have more than one branded link, the default is determined by the following order:\n\n* The validated branded link marked as `default` (set when you call the \"Create a branded link\" endpoint or by calling the \"Update a branded link\" endpoint on an existing link)\n* Legacy branded links (migrated from the whitelabel wizard)\n* Default SendGrid-branded links (i.e., `100.ct.sendgrid.net`)\n\nYou can submit this request as one of your subusers if you include their ID in the `on-behalf-of` header in the request.", "parameters": [ { "name": "domain", "in": "query", "description": "The domain to match against when finding the default branded link.", "type": "string" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/link_branding_200_response" }, "examples": { "application/json": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "john@example.com", "user_id": 7, "default": false, "valid": true, "legacy": false, "dns": { "domain_cname": { "valid": true, "type": "cname", "host": "mail.example.com", "data": "sendgrid.net" }, "owner_cname": { "valid": true, "type": "cname", "host": "7.example.com", "data": "sendgrid.net" } } } } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/links/subuser": { "get": { "operationId": "GET_whitelabel-links-subuser", "summary": "Retrieve a subuser's branded link", "tags": [ "Link branding" ], "description": "**This endpoint allows you to retrieve the branded link associated with a subuser.**\n\nLink branding can be associated with subusers from the parent account. This functionality allows subusers to send mail using their parent's link branding. To associate link branding, the parent account must first create a branded link and then validate it. The parent may then associate that branded link with a subuser via the API or the [Subuser Management page of the Twilio SendGrid App](https://app.sendgrid.com/settings/subusers).", "parameters": [ { "name": "username", "in": "query", "description": "The username of the subuser to retrieve associated branded links for.", "required": true, "type": "string" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/link_branding_200_response" }, "examples": { "application/json": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "john@example.com", "user_id": 7, "default": false, "valid": true, "legacy": false, "dns": { "domain_cname": { "valid": true, "type": "cname", "host": "mail.example.com", "data": "sendgrid.net" }, "owner_cname": { "valid": true, "type": "cname", "host": "7.example.com", "data": "sendgrid.net" } } } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_whitelabel-links-subuser", "summary": "Disassociate a branded link from a subuser", "tags": [ "Link branding" ], "description": "**This endpoint allows you to take a branded link away from a subuser.**\n\nLink branding can be associated with subusers from the parent account. This functionality allows subusers to send mail using their parent's link branding. To associate link branding, the parent account must first create a branded link and validate it. The parent may then associate that branded link with a subuser via the API or the [Subuser Management page of the Twilio SendGrid App](https://app.sendgrid.com/settings/subusers).\n\nYour request will receive a response with a 204 status code if the disassociation was successful.", "parameters": [ { "name": "username", "in": "query", "description": "The username of the subuser account that you want to disassociate a branded link from.", "required": true, "type": "string" } ], "responses": { "204": { "description": "", "schema": { "type": "object" } } }, "security": [ { "Authorization": [] } ] } }, "/ips/warmup": { "post": { "operationId": "POST_ips-warmup", "summary": "Start warming up an IP address", "tags": [ "IP Warmup" ], "description": "**This endpoint allows you to put an IP address into warmup mode.**", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "The IP address that you want to begin warming up." } }, "example": { "ip": "0.0.0.0" } } } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/ip_warmup_response" }, "examples": { "application/json": [ { "ip": "0.0.0.0", "start_date": 1409616000 } ] } }, "404": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "description": "The errors that were encountered.", "items": { "type": "object", "properties": { "field": { "type": "null" }, "message": { "type": "string", "description": "A message explaining why the IP couldn't entered into warmup mode." } } } } } }, "examples": { "application/json": { "errors": [ { "field": null, "message": "resource not found" } ] } } } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_ips-warmup", "summary": "Retrieve all IPs currently in warmup", "tags": [ "IP Warmup" ], "description": "**This endpoint allows you to retrieve all of your IP addresses that are currently warming up.**", "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/ip_warmup_response" }, "examples": { "application/json": [ { "ip": "0.0.0.0", "start_date": 1409616000 } ] } } }, "security": [ { "Authorization": [] } ] } }, "/ips/warmup/{ip_address}": { "parameters": [ { "name": "ip_address", "in": "path", "description": "The IP address that you want to retrieve the warmup status for.", "required": true, "type": "string" } ], "get": { "operationId": "GET_ips-warmup-ip_address", "summary": "Retrieve the warmup status for a specific IP address", "tags": [ "IP Warmup" ], "description": "**This endpoint allows you to retrieve the warmup status for a specific IP address.**\n\nYou can retrieve all of your warming IPs using the \"Retrieve all IPs currently in warmup\" endpoint.", "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/ip_warmup_response" }, "examples": { "application/json": [ { "ip": "0.0.0.0", "start_date": 1409616000 } ] } }, "404": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "description": "The errors that were encountered.", "items": { "type": "object", "properties": { "field": { "type": "null" }, "message": { "type": "string", "description": "A message explaining why the warmup status could not be retrieved." } } } } } }, "examples": { "application/json": { "errors": [ { "field": null, "message": "resource not found" } ] } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_ips-warmup-ip_address", "summary": "Stop warming up an IP address", "tags": [ "IP Warmup" ], "description": "**This endpoint allows you to remove an IP address from warmup mode.**\n\nYour request will return a 204 status code if the specified IP was successfully removed from warmup mode. To retrieve details of the IP’s warmup status *before* removing it from warmup mode, call the \"Retrieve the warmpup status for a specific IP address\" endpoint.", "responses": { "204": { "description": "", "schema": { "type": "object" } }, "404": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "description": "The errors that were encountered.", "items": { "type": "object", "properties": { "field": { "type": "null" }, "message": { "type": "string", "description": "A message explaining why the IP couldn't be removed from warmup." } } } } } }, "examples": { "application/json": { "errors": [ { "field": null, "message": "resource not found" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/ips": { "post": { "operationId": "POST_whitelabel-ips", "summary": "Set up reverse DNS", "tags": [ "Reverse DNS" ], "description": "**This endpoint allows you to set up reverse DNS.**", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "The IP address for which you want to set up reverse DNS." }, "subdomain": { "type": "string", "description": "The subdomain that will be used to send emails from the IP address. This should be the same as the subdomain used to set up an authenticated domain." }, "domain": { "type": "string", "description": "The root, or sending, domain that will be used to send message from the IP address." } }, "required": [ "ip", "domain" ], "example": { "ip": "192.168.1.1", "subdomain": "email", "domain": "example.com" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "201": { "description": "", "schema": { "$ref": "#/definitions/reverse_dns" }, "examples": { "application/json": { "id": 123, "ip": "192.168.1.2", "rdns": "o1.email.example.com", "users": [], "subdomain": "email", "domain": "example.com", "valid": true, "legacy": false, "a_record": { "valid": true, "type": "a", "host": "o1.email.example.com", "data": "192.168.1.2" } } } } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_whitelabel-ips", "summary": "Retrieve all reverse DNS records", "tags": [ "Reverse DNS" ], "description": "**This endpoint allows you to retrieve all of the Reverse DNS records created by this account.**\n\nYou may include a search key by using the `ip` query string parameter. This enables you to perform a prefix search for a given IP segment (e.g., `?ip=\"192.\"`).\n\nUse the `limit` query string parameter to reduce the number of records returned. All records will be returned if you have fewer records than the specified limit.\n\nThe `offset` query string parameter allows you to specify a non-zero index from which records will be returned. For example, if you have ten records, `?offset=5` will return the last five records (at indexes 5 through 9). The list starts at index zero.", "parameters": [ { "name": "limit", "in": "query", "description": "The maximum number of results to retrieve.", "type": "integer" }, { "name": "offset", "in": "query", "description": "The point in the list of results to begin retrieving IP addresses from.", "type": "integer" }, { "name": "ip", "in": "query", "description": "The IP address segment that you'd like to use in a prefix search.", "type": "string" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "array", "items": { "$ref": "#/definitions/reverse_dns" } }, "examples": { "application/json": [ { "id": 1, "ip": "192.168.1.1", "rdns": "o1.email.example.com", "users": [ { "username": "john@example.com", "user_id": 7 }, { "username": "jane@example.com", "user_id": 8 } ], "subdomain": "email", "domain": "example.com", "valid": true, "legacy": false, "a_record": { "valid": true, "type": "a", "host": "o1.email.example.com", "data": "192.168.1.1" } }, { "id": 2, "ip": "192.168.1.2", "rdns": "o2.email.example.com", "users": [ { "username": "john@example.com", "user_id": 7 }, { "username": "jane@example2.com", "user_id": 9 } ], "subdomain": "email", "domain": "example.com", "valid": true, "legacy": false, "a_record": { "valid": true, "type": "a", "host": "o2.email.example.com", "data": "192.168.1.2" } } ] } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/ips/{id}/validate": { "parameters": [ { "name": "id", "in": "path", "description": "The ID of the reverse DNS record that you would like to validate.", "required": true, "type": "string" } ], "post": { "operationId": "POST_whitelabel-ips-id-validate", "summary": "Validate a reverse DNS record", "tags": [ "Reverse DNS" ], "description": "**This endpoint allows you to validate a reverse DNS record.**\n\nAlways check the `valid` property of the response’s `validation_results.a_record` object. This field will indicate whether it was possible to validate the reverse DNS record. If the `validation_results.a_record.valid` is `false`, this indicates only that Twilio SendGrid could not determine the validity your reverse DNS record — it may still be valid.\n\nIf validity couldn’t be determined, you can check the value of `validation_results.a_record.reason` to find out why.\n\nYou can retrieve the IDs associated with all your reverse DNS records using the \"Retrieve all reverse DNS records\" endpoint.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the reverse DNS record." }, "valid": { "type": "boolean", "description": "Indicates if the reverse DNS record is valid.", "enum": [ true, false ] }, "validation_results": { "type": "object", "description": "The specific results of the validation.", "properties": { "a_record": { "type": "object", "properties": { "valid": { "type": "boolean", "description": "Indicates if the reverse DNS record could be validated.", "enum": [ true, false ] }, "reason": { "type": [ "null", "string" ], "description": "The reason the reverse DNS record could not be validated. Is `null` if the reverse DNS record was validated." } }, "required": [ "valid", "reason" ] } } } }, "required": [ "id", "valid", "validation_results" ] }, "examples": { "application/json": { "id": 123456, "valid": false, "validation_results": { "a_record": { "valid": false, "reason": "Failed to resolve A Record at o1.ptr4283.example.com: lookup o1.ptr4283.example.com on 192.168.0.10:53: no such host" } } } } }, "404": { "description": "Unexpected error in API call. See HTTP response body for details.", "schema": { "type": "object", "properties": { "errors": { "type": "array", "description": "The error messages for the failed validation.", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "A message describing why the reverse DNS could not be validated." } }, "required": [ "message" ] } } }, "required": [ "errors" ] }, "examples": { "application/json": { "errors": [ { "message": "Reverse DNS record not found." } ] } } }, "500": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "description": "The error messages for the failed validation.", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "A message describing why the IP whitelabel could not be validated." } }, "required": [ "message" ] } } }, "required": [ "errors" ] }, "examples": { "application/json": { "errors": [ { "message": "internal error getting rDNS" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/ips/{id}": { "parameters": [ { "name": "id", "in": "path", "description": "The ID of the reverse DNS record that you would like to retrieve.", "required": true, "type": "string" } ], "get": { "operationId": "GET_whitelabel-ips-id", "summary": "Retrieve a reverse DNS record", "tags": [ "Reverse DNS" ], "description": "**This endpoint allows you to retrieve a reverse DNS record.**\n\nYou can retrieve the IDs associated with all your reverse DNS records using the \"Retrieve all reverse DNS records\" endpoint.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/reverse_dns" }, "examples": { "application/json": { "id": 123, "ip": "192.168.1.1", "rdns": "o1.email.example.com", "users": [ { "username": "john@example.com", "user_id": 7 } ], "subdomain": "email", "domain": "example.com", "valid": true, "legacy": false, "a_record": { "valid": true, "type": "a", "host": "o1.email.example.com", "data": "192.168.1.1" } } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_whitelabel-ips-id", "summary": "Delete a reverse DNS record", "tags": [ "Reverse DNS" ], "description": "**This endpoint allows you to delete a reverse DNS record.**\n\nA call to this endpoint will respond with a 204 status code if the deletion was successful.\n\nYou can retrieve the IDs associated with all your reverse DNS records using the \"Retrieve all reverse DNS records\" endpoint.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "204": { "description": "", "schema": { "type": "object" } } }, "security": [ { "Authorization": [] } ] } }, "/validations/email": { "post": { "operationId": "POST_validations-email", "summary": "Validate an email", "tags": [ "Email Address Validation" ], "description": "**This endpoint allows you to validate an email address.**", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "The email address that you want to validate." }, "source": { "type": "string", "description": "A one-word classifier for where this validation originated." } }, "required": [ "email" ], "example": { "email": "example@example.com", "source": "signup" } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "result": { "type": "object", "required": [ "email", "verdict", "score", "local", "host", "checks", "ip_address" ], "properties": { "email": { "type": "string", "description": "The email being validated", "format": "email" }, "verdict": { "type": "string", "description": "A generic classification of whether or not the email address is valid.", "enum": [ "Valid", "Risky", "Invalid" ] }, "score": { "type": "number", "description": "A numeric representation of the email validity." }, "local": { "type": "string", "description": "The local part of the email address." }, "host": { "type": "string", "description": "The domain of the email address.", "format": "hostname" }, "suggestion": { "type": "string", "description": "A suggested correction in the event of domain name typos (e.g., gmial.com)" }, "checks": { "type": "object", "description": "Granular checks for email address validity.", "required": [ "domain", "local_part", "additional" ], "properties": { "domain": { "type": "object", "description": "Checks on the domain portion of the email address.", "required": [ "has_valid_address_syntax", "has_mx_or_a_record", "is_suspected_disposable_address" ], "properties": { "has_valid_address_syntax": { "type": "boolean", "description": "Whether the email address syntax is valid." }, "has_mx_or_a_record": { "type": "boolean", "description": "Whether the email has appropriate DNS records to deliver a message. " }, "is_suspected_disposable_address": { "type": "boolean", "description": "Whether the domain appears to be from a disposable email address service." } } }, "local_part": { "type": "object", "description": "Checks on the local part of the email address.", "required": [ "is_suspected_role_address" ], "properties": { "is_suspected_role_address": { "type": "boolean", "description": "Whether the local part of email appears to be a role or group (e.g., hr, admin)" } } }, "additional": { "type": "object", "description": "Additional checks on the email address.", "required": [ "has_known_bounces", "has_suspected_bounces" ], "properties": { "has_known_bounces": { "type": "boolean", "description": "WHether email sent to this address from your account has bounced." }, "has_suspected_bounces": { "type": "boolean", "description": "Whether our model predicts that the email address might bounce." } } } } }, "source": { "type": "string", "description": "The source of the validation, as per the API request." }, "ip_address": { "type": "string", "description": "The IP address associated with this email." } } } }, "required": [ "result" ] }, "examples": { "application/json": { "result": { "email": "cedric@fogowl.com", "verdict": "Valid", "score": 0.85021, "local": "cedric", "host": "fogowl.com", "checks": { "domain": { "has_valid_address_syntax": true, "has_mx_or_a_record": true, "is_suspected_disposable_address": false }, "local_part": { "is_suspected_role_address": false }, "additional": { "has_known_bounces": false, "has_suspected_bounces": false } }, "ip_address": "192.168.1.1" } } } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/dns/email": { "post": { "operationId": "POST_whitelabel-dns-email", "summary": "Email DNS records to a co-worker", "tags": [ "Email CNAME records" ], "description": "**This endpoint is used to share DNS records with a colleagues**\n\nUse this endpoint to send SendGrid-generated DNS record information to a co-worker so they can enter it into your DNS provider to validate your domain and link branding. \n\nWhat type of records are sent will depend on whether you have chosen Automated Security or not. When using Automated Security, SendGrid provides you with three CNAME records. If you turn Automated Security off, you are instead given TXT and MX records.\n\nIf you pass a `link_id` to this endpoint, the generated email will supply the DNS records necessary to complete [Link Branding](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-link-branding/) setup. If you pass a `domain_id` to this endpoint, the generated email will supply the DNS records needed to complete [Domain Authentication](https://sendgrid.com/docs/ui/account-and-settings/how-to-set-up-domain-authentication/). Passing both IDs will generate an email with the records needed to complete both setup steps.\n\nYou can retrieve all your domain IDs from the returned `id` fields for each domain using the \"List all authenticated domains\" endpoint. You can retrieve all of your link IDs using the \"Retrieve all branded links\" endpoint.", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "link_id": { "type": "integer", "minimum": 0, "desc": "The ID of the branded link." }, "domain_id": { "type": "integer", "minimum": 0, "description": "The ID of your SendGrid domain record." }, "email": { "type": "string", "format": "email", "description": "The email address to send the DNS information to." }, "message": { "type": "string", "default": "Please set these DNS records in our hosting solution.", "description": "A custom text block to include in the email body sent with the records." } }, "required": [ "link_id", "domain_id", "email" ], "example": { "link_id": 29719392, "domain_id": 46873408, "email": "my_colleague@example.com", "message": "DNS Record for verification" } } } ], "responses": { "204": { "description": "" }, "400": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "object", "properties": { "error": { "type": "string" }, "field": { "type": "string" } } } } } } }, "security": [ { "Authorization": [] } ] } }, "/ips/pools": { "post": { "operationId": "POST_ips-pools", "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**.", "parameters": [ { "name": "body", "in": "body", "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": "", "schema": { "$ref": "#/definitions/ip_pool_response" }, "examples": { "application/json": { "name": "marketing" } } } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_ips-pools", "summary": "Retrieve all IP pools", "tags": [ "IP Pools" ], "description": "**This endpoint allows you to get all of your IP pools.**", "responses": { "200": { "description": "", "schema": { "type": "array", "items": { "$ref": "#/definitions/ip_pool_response" } }, "examples": { "application/json": [ { "name": "marketing" }, { "name": "transactional" } ] } } }, "security": [ { "Authorization": [] } ] } }, "/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, "type": "string" } ], "post": { "operationId": "POST_ips-pools-pool_name-ips", "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.", "parameters": [ { "name": "body", "in": "body", "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": "", "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": { "application/json": { "ip": "000.00.00.0", "pools": [ "test1" ], "start_date": 1409616000, "warmup": true } } }, "404": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "description": "The error returned.", "items": { "type": "object", "properties": { "field": { "type": "null" }, "message": { "type": "string", "description": "A message explaining why the IP address could not be added to the IP Pool." } } } } } }, "examples": { "application/json": { "errors": [ { "field": null, "message": "resource not found" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/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, "type": "string" } ], "get": { "operationId": "GET_ips-pools-pool_name", "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": "", "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": { "application/json": { "pool_name": "Sample", "ips": [ "192.168.1.1", "192.158.1.2", "192.138.2.1" ] } } }, "404": { "description": "", "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": { "application/json": { "errors": [ { "field": "error", "message": "Unable to locate specified IPs Pool" } ] } } } }, "security": [ { "Authorization": [] } ] }, "put": { "operationId": "PUT_ips-pools-pool_name", "summary": "Rename an IP pool", "tags": [ "IP Pools" ], "description": "**This endpoint allows you to update the name of an IP pool.**", "parameters": [ { "name": "body", "in": "body", "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": "", "schema": { "$ref": "#/definitions/ip_pool_response" }, "examples": { "application/json": { "name": "new_pool_name" } } }, "404": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "null" }, "message": { "type": "string", "description": "A message explaining why the name of your IP pool could not be updated." } } } } } }, "examples": { "application/json": { "errors": [ { "field": null, "message": "ip pool not found" } ] } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_ips-pools-pool_name", "summary": "Delete an IP pool", "tags": [ "IP Pools" ], "description": "**This endpoint allows you to delete an IP pool.**", "responses": { "204": { "description": "", "schema": { "type": "object" } }, "404": { "description": "", "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "An error explaining why the pool could not be deleted." } } }, "examples": { "application/json": { "error": "Unable to locate specified IPs Pool" } } } }, "security": [ { "Authorization": [] } ] } }, "/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, "type": "string" }, { "name": "ip", "in": "path", "description": "The IP address that you wish to remove.", "required": true, "type": "string" } ], "delete": { "operationId": "DELETE_ips-pools-pool_name-ips-ip", "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": "", "schema": { "type": "object" } }, "404": { "description": "", "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "An error explaining why the IP address could not be removed from the IP pool." } } }, "examples": { "application/json": { "error": "Unable to locate specified IPs Pool" } } } }, "security": [ { "Authorization": [] } ] } }, "/ips": { "post": { "operationId": "POST_ips", "summary": "Add IPs", "tags": [ "IP Addresses" ], "description": "**This endpoint is for adding a(n) IP Address(es) to your account.**", "parameters": [ { "name": "body", "in": "body", "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": "", "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": { "application/json": { "ips": [ { "ip": "1.2.3.4", "subusers": [ "user", "subuser1" ] }, { "ip": "1.2.3.5", "subusers": [ "user", "subuser1" ] } ], "remaining_ips": 1, "warmup": true } } }, "400": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "one or more subusers do not belong to this user" } ] } } } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_ips", "summary": "Retrieve all IP addresses", "tags": [ "IP Addresses" ], "description": "**This endpoint allows you to retrieve a 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 based on the aggregate performance of all the senders who use it.", "parameters": [ { "name": "ip", "in": "query", "description": "The IP address to get", "type": "string" }, { "name": "exclude_whitelabels", "in": "query", "description": "Should we exclude reverse DNS records (whitelabels)?", "type": "boolean" }, { "name": "limit", "in": "query", "description": "The number of IPs you want returned at the same time.", "type": "integer", "default": 10 }, { "name": "offset", "in": "query", "description": "The offset for the number of IPs that you are requesting.", "type": "integer", "default": 0 }, { "name": "subuser", "in": "query", "description": "The subuser you are requesting for.", "type": "string" }, { "name": "sort_by_direction", "in": "query", "description": "The direction to sort the results.", "type": "string", "enum": [ "desc", "asc" ] } ], "responses": { "200": { "description": "", "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": { "type": [ "number", "null" ], "description": "The date that the IP address was entered into warmup." }, "whitelabeled": { "type": "boolean", "description": "Indicates if this IP address is associated with a reverse DNS record." }, "assigned_at": { "type": [ "integer", "null" ], "description": "The date that the IP address was assigned to the user." } }, "required": [ "ip", "subusers", "pools", "warmup", "start_date", "whitelabeled", "assigned_at" ] } }, "examples": { "application/json": [ { "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.burgermail.com", "start_date": 1409616000, "subusers": [], "warmup": false, "assigned_at": 1482883200 } ] } } }, "security": [ { "Authorization": [] } ] } }, "/ips/remaining": { "get": { "operationId": "GET_ips-remaining", "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": "", "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": { "application/json": { "results": [ { "remaining": 2, "period": "month", "price_per_ip": 20 } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/ips/assigned": { "get": { "operationId": "GET_ips-assigned", "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": "", "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": { "application/json": [ { "ip": "167.89.21.3", "pools": [ "new_test5" ], "warmup": true, "start_date": 1409616000 } ] } } }, "security": [ { "Authorization": [] } ] } }, "/ips/{ip_address}": { "parameters": [ { "name": "ip_address", "in": "path", "description": "The IP address you are retrieving the IP pools for.", "required": true, "type": "string" } ], "get": { "operationId": "GET_ips-ip_address", "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": "", "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": { "type": [ "integer", "null" ], "description": "The date that the IP address was entered into warmup." }, "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": { "application/json": { "ip": "000.00.00.0", "subusers": [ "subuser1", "subuser2" ], "rdns": "o1.em.example.com", "pools": [ "test1" ], "warmup": false, "start_date": null, "whitelabeled": true } } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/domains": { "get": { "operationId": "GET_whitelabel-domains", "summary": "List all authenticated domains", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to retrieve a list of all domains you have authenticated.**", "parameters": [ { "name": "limit", "in": "query", "description": "Number of domains to return.", "type": "integer" }, { "name": "offset", "in": "query", "description": "Paging offset.", "type": "integer" }, { "name": "exclude_subusers", "in": "query", "description": "Exclude subuser domains from the result.", "type": "boolean" }, { "name": "username", "in": "query", "description": "The username associated with an authenticated domain.", "type": "string" }, { "name": "domain", "in": "query", "description": "Search for authenticated domains.", "type": "string" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/domain-authentication-200-response" }, "examples": { "application/json": [ { "id": 1, "user_id": 7, "subdomain": "mail", "domain": "example.com", "username": "jane@example.com", "ips": [ "192.168.1.1", "192.168.1.2" ], "custom_spf": true, "default": true, "legacy": false, "automatic_security": true, "valid": true, "dns": { "mail_cname": { "valid": true, "type": "cname", "host": "mail.example.com", "data": "u7.wl.sendgrid.net" }, "dkim1": { "valid": true, "type": "cname", "host": "s1._domainkey.example.com", "data": "s1._domainkey.u7.wl.sendgrid.net" }, "dkim2": { "valid": true, "type": "cname", "host": "s2._domainkey.example.com", "data": "s2._domainkey.u7.wl.sendgrid.net" } } }, { "id": 2, "user_id": 8, "subdomain": "new", "domain": "example2.com", "username": "john@example2.com", "ips": [], "custom_spf": false, "default": true, "legacy": false, "automatic_security": true, "valid": false, "dns": { "mail_cname": { "valid": false, "type": "mx", "host": "news.example2.com", "data": "sendgrid.net" }, "dkim1": { "valid": false, "type": "txt", "host": "example2.com", "data": "k=rsa; t=s; p=publicKey" }, "dkim2": { "valid": false, "type": "txt", "host": "example2.com", "data": "k=rsa; t=s p=publicKey" } } } ] } } }, "security": [ { "Authorization": [] } ] }, "post": { "operationId": "POST_whitelabel-domains", "summary": "Authenticate a domain", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to authenticate a domain.**\n\nIf you are authenticating a domain for a subuser, you have two options:\n1. Use the \"username\" parameter. This allows you to authenticate a domain on behalf of your subuser. This means the subuser is able to see and modify the authenticated domain.\n2. Use the Association workflow (see Associate Domain section). This allows you to authenticate a domain created by the parent to a subuser. This means the subuser will default to the assigned domain, but will not be able to see or modify that authenticated domain. However, if the subuser authenticates their own domain it will overwrite the assigned domain.", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "domain": { "type": "string", "description": "Domain being authenticated." }, "subdomain": { "type": "string", "description": "The subdomain to use for this authenticated domain." }, "username": { "type": "string", "description": "The username associated with this domain." }, "ips": { "type": "array", "description": "The IP addresses that will be included in the custom SPF record for this authenticated domain.", "items": { "type": "string" } }, "custom_spf": { "type": "boolean", "description": "Specify whether to use a custom SPF or allow SendGrid to manage your SPF. This option is only available to authenticated domains set up for manual security." }, "default": { "type": "boolean", "description": "Whether to use this authenticated domain as the fallback if no authenticated domains match the sender's domain." }, "automatic_security": { "type": "boolean", "description": "Whether to allow SendGrid to manage your SPF records, DKIM keys, and DKIM key rotation." }, "custom_dkim_selector": { "type": "string", "description": "Add a custom DKIM selector. Accepts three letters or numbers." } }, "required": [ "domain" ], "example": { "domain": "example.com", "subdomain": "news", "username": "john@example.com", "ips": [ "192.168.1.1", "192.168.1.2" ], "custom_spf": true, "default": true, "automatic_security": false } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "201": { "description": "", "schema": { "$ref": "#/definitions/authentication::domain" }, "examples": { "application/json": { "id": 302183, "user_id": 1446226, "subdomain": "example", "domain": "example.com", "username": "mbernier", "ips": [], "custom_spf": false, "default": true, "legacy": false, "automatic_security": true, "valid": false, "dns": { "mail_cname": { "valid": false, "type": "cname", "host": "example.example.com", "data": "u1446226.wl.sendgrid.net" }, "dkim1": { "valid": false, "type": "cname", "host": "s1._domainkey.example.com", "data": "s1.domainkey.u1446226.wl.sendgrid.net" }, "dkim2": { "valid": false, "type": "cname", "host": "s2._domainkey.example.com", "data": "s2.domainkey.u1446226.wl.sendgrid.net" } } } } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/domains/{domain_id}": { "parameters": [ { "name": "domain_id", "in": "path", "required": true, "type": "string" } ], "get": { "operationId": "GET_whitelabel-domains-domain_id", "summary": "Retrieve an authenticated domain", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to retrieve a specific authenticated domain.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/authentication::domain" }, "examples": { "application/json": { "id": 45373692, "user_id": 66036447, "subdomain": "sub", "domain": "example.com", "username": "jdoe", "ips": [ "127.0.0.1" ], "custom_spf": false, "default": true, "legacy": false, "automatic_security": true, "valid": true, "dns": { "mail_cname": { "valid": true, "type": "cname", "host": "mail.example.com", "data": "u7.wl.sendgrid.net" }, "dkim1": { "valid": true, "type": "cname", "host": "s1._domainkey.example.com", "data": "s1._domainkey.u7.wl.sendgrid.net" }, "dkim2": { "valid": true, "type": "cname", "host": "s2._domainkey.example.com", "data": "s2._domainkey.u7.wl.sendgrid.net" } } } } } }, "security": [ { "Authorization": [] } ] }, "patch": { "operationId": "PATCH_whitelabel-domains-domain_id", "summary": "Update an authenticated domain", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to update the settings for an authenticated domain.**", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "default": { "type": "boolean", "default": false, "description": "Indicates whether this is the default authenticated domain." }, "custom_spf": { "type": "boolean", "default": false, "description": "Indicates whether to generate a custom SPF record for manual security." } }, "example": { "default": false, "custom_spf": true } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/domain-authentication-200-response" }, "examples": { "application/json": [ { "id": 1, "user_id": 7, "subdomain": "mail", "domain": "example.com", "username": "jane@example.com", "ips": [ "192.168.1.1", "192.168.1.2" ], "custom_spf": true, "default": true, "legacy": false, "automatic_security": true, "valid": true, "dns": { "mail_cname": { "valid": true, "type": "cname", "host": "mail.example.com", "data": "u7.wl.sendgrid.net" }, "dkim1": { "valid": true, "type": "cname", "host": "s1._domainkey.example.com", "data": "s1._domainkey.u7.wl.sendgrid.net" }, "dkim2": { "valid": true, "type": "cname", "host": "s2._domainkey.example.com", "data": "s2._domainkey.u7.wl.sendgrid.net" } } }, { "id": 2, "user_id": 8, "subdomain": "new", "domain": "example2.com", "username": "john@example2.com", "ips": [], "custom_spf": false, "default": true, "legacy": false, "automatic_security": true, "valid": false, "dns": { "mail_cname": { "valid": false, "type": "mx", "host": "news.example2.com", "data": "sendgrid.net" }, "dkim1": { "valid": false, "type": "txt", "host": "example2.com", "data": "k=rsa; t=s; p=publicKey" }, "dkim2": { "valid": false, "type": "txt", "host": "example2.com", "data": "k=rsa; t=s p=publicKey" } } } ] } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_whitelabel-domains-domain_id", "summary": "Delete an authenticated domain.", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to delete an authenticated domain.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "204": { "description": "", "schema": { "type": "object" } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/domains/default": { "get": { "operationId": "GET_whitelabel-domains-default", "summary": "Get the default authentication", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to retrieve the default authentication for a domain.**\n\nWhen creating or updating a domain authentication, you can set the domain as a default. The default domain will be used to send all mail. If you have multiple authenticated domains, the authenticated domain matching the domain of the From address will be used, and the default will be overridden.\n\nThis endpoint will return a default domain and its details only if a default is set. You are not required to set a default. If you do not set a default domain, this endpoint will return general information about your domain authentication status.", "parameters": [ { "name": "domain", "in": "query", "description": "The domain to find a default authentication.", "type": "string" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/domain-authentication-200-response" }, "examples": { "application/json": [ { "id": 1, "user_id": 7, "subdomain": "mail", "domain": "example.com", "username": "jane@example.com", "ips": [ "192.168.1.1", "192.168.1.2" ], "custom_spf": true, "default": true, "legacy": false, "automatic_security": true, "valid": true, "dns": { "mail_cname": { "valid": true, "type": "cname", "host": "mail.example.com", "data": "u7.wl.sendgrid.net" }, "dkim1": { "valid": true, "type": "cname", "host": "s1._domainkey.example.com", "data": "s1._domainkey.u7.wl.sendgrid.net" }, "dkim2": { "valid": true, "type": "cname", "host": "s2._domainkey.example.com", "data": "s2._domainkey.u7.wl.sendgrid.net" } } } ] } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/domains/{id}/ips": { "parameters": [ { "name": "id", "in": "path", "description": "ID of the domain to which you are adding an IP", "required": true, "type": "integer" } ], "post": { "operationId": "POST_whitelabel-domains-id-ips", "summary": "Add an IP to an authenticated domain", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to add an IP address to an authenticated domain.**", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "ip": { "type": "string", "description": "IP to associate with the domain. Used for manually specifying IPs for custom SPF." } }, "required": [ "ip" ], "example": { "ip": "192.168.0.1" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/domain_authentication:domain_spf" }, "examples": { "application/json": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "john@example.com", "user_id": 7, "ips": [], "custom_spf": true, "default": false, "legacy": false, "automatic_security": false, "valid": false, "dns": { "mail_server": { "host": "mail.example.com", "type": "mx", "data": "sendgrid.net", "valid": false }, "subdomain_spf": { "host": "mail.example.com", "type": "txt", "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", "valid": false }, "domain_spf": { "host": "example.com", "type": "txt", "data": "v=spf1 include:mail.example.com -all", "valid": false }, "dkim": { "host": "s1._domainkey.example.com", "type": "txt", "data": "k=rsa; t=s; p=publicKey", "valid": false } } } } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/domains/{id}/ips/{ip}": { "parameters": [ { "name": "id", "in": "path", "description": "ID of the domain to delete the IP from.", "required": true, "type": "integer" }, { "name": "ip", "in": "path", "description": "IP to remove from the domain.", "required": true, "type": "string" } ], "delete": { "operationId": "DELETE_whitelabel-domains-id-ips-ip", "summary": "Remove an IP from an authenticated domain.", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to remove an IP address from that domain's authentication.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/domain_authentication:domain_spf" }, "examples": { "application/json": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "mail@example.com", "user_id": 7, "ips": [], "custom_spf": true, "default": false, "legacy": false, "automatic_security": false, "valid": false, "dns": { "mail_server": { "host": "mail.example.com", "type": "mx", "data": "sendgrid.net", "valid": false }, "subdomain_spf": { "host": "mail.example.com", "type": "txt", "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", "valid": false }, "domain_spf": { "host": "example.com", "type": "txt", "data": "v=spf1 include:mail.example.com -all", "valid": false }, "dkim": { "host": "s1._domainkey.example.com", "type": "txt", "data": "k=rsa; t=s; p=publicKey", "valid": false } } } } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/domains/{id}/validate": { "parameters": [ { "name": "id", "in": "path", "description": "ID of the domain to validate.", "required": true, "type": "integer" } ], "post": { "operationId": "POST_whitelabel-domains-id-validate", "summary": "Validate a domain authentication.", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to validate an authenticated domain. If it fails, it will return an error message describing why the domain could not be validated.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "id": { "type": "integer", "description": "The ID of the authenticated domain." }, "valid": { "type": "boolean", "description": "Indicates if this is a valid authenticated domain." }, "validation_results": { "type": "object", "description": "The individual DNS records that are checked when validating, including the reason for any invalid DNS records.", "properties": { "mail_cname": { "type": "object", "description": "The CNAME record for the authenticated domain.", "properties": { "valid": { "type": "boolean", "description": "Indicates if this DNS record is valid." }, "reason": { "type": [ "string", "null" ], "description": "The reason this record is invalid." } } }, "dkim1": { "type": "object", "description": "A DNS record for this authenticated domain.", "properties": { "valid": { "type": "boolean", "description": "Indicates if the DNS record is valid." }, "reason": { "type": [ "string", "null" ] } } }, "dkim2": { "type": "object", "description": "A DNS record for this authenticated domain.", "properties": { "valid": { "type": "boolean", "description": "Indicates if the DNS record is valid." }, "reason": { "type": [ "string", "null" ] } } }, "spf": { "type": "object", "description": "The SPF record for the authenticated domain.", "properties": { "valid": { "type": "boolean", "description": "Indicates if the SPF record is valid." }, "reason": { "type": [ "string", "null" ] } } } } } } }, "examples": { "application/json": { "id": 1, "valid": true, "validation_resuts": { "mail_cname": { "valid": false, "reason": "Expected your MX record to be \"mx.sendgrid.net\" but found \"example.com\"." }, "dkim1": { "valid": true, "reason": null }, "dkim2": { "valid": true, "reason": null }, "spf": { "valid": true, "reason": null } } } } }, "500": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "A message explaining the reason for the error." } }, "required": [ "message" ] } } } }, "examples": { "application/json": { "errors": [ { "message": "internal error getting TXT" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/domains/subuser": { "get": { "operationId": "GET_whitelabel-domains-subuser", "summary": "List the authenticated domain associated with the given user.", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to retrieve all of the authenticated domains that have been assigned to a specific subuser.**\n\nAuthenticated domains can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's domain authentication. To associate an authenticated domain with a subuser, the parent account must first authenticate and validate the domain. The parent may then associate the authenticated domain via the subuser management tools.", "parameters": [ { "name": "username", "in": "query", "description": "Username for the subuser to find associated authenticated domain.", "required": true, "type": "string" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/domain_authentication:domain_spf" }, "examples": { "application/json": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "mail@example.com", "user_id": 7, "ips": [], "custom_spf": true, "default": false, "legacy": false, "automatic_security": false, "valid": false, "dns": { "mail_server": { "host": "mail.example.com", "type": "mx", "data": "sendgrid.net", "valid": false }, "subdomain_spf": { "host": "mail.example.com", "type": "txt", "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", "valid": false }, "domain_spf": { "host": "example.com", "type": "txt", "data": "v=spf1 include:mail.example.com -all", "valid": false }, "dkim": { "host": "s1._domainkey.example.com", "type": "txt", "data": "k=rsa; t=s; p=publicKey", "valid": false } } } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_whitelabel-domains-subuser", "summary": "Disassociate an authenticated domain from a given user.", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to disassociate a specific authenticated domain from a subuser.**\n\nAuthenticated domains can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's domain authentication. To associate an authenticated domain with a subuser, the parent account must first authenticate and validate the domain. The parent may then associate the authenticated domain via the subuser management tools.", "parameters": [ { "name": "username", "in": "query", "description": "Username for the subuser to find associated authenticated domain.", "type": "string" } ], "responses": { "204": { "description": "", "schema": { "type": "object" } } }, "security": [ { "Authorization": [] } ] } }, "/whitelabel/domains/{domain_id}/subuser": { "parameters": [ { "name": "domain_id", "in": "path", "description": "ID of the authenticated domain to associate with the subuser", "required": true, "type": "integer" } ], "post": { "operationId": "POST_whitelabel-domains-domain_id-subuser", "summary": "Associate an authenticated domain with a given user.", "tags": [ "Domain Authentication" ], "description": "**This endpoint allows you to associate a specific authenticated domain with a subuser.**\n\nAuthenticated domains can be associated with (i.e. assigned to) subusers from a parent account. This functionality allows subusers to send mail using their parent's domain authentication. To associate an authenticated domain with a subuser, the parent account must first authenticate and validate the domain. The parent may then associate the authenticated domain via the subuser management tools.", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "Username to associate with the authenticated domain." } }, "required": [ "username" ], "example": { "username": "jdoe" } } } ], "responses": { "201": { "description": "", "schema": { "$ref": "#/definitions/domain_authentication:domain_spf" }, "examples": { "application/json": { "id": 1, "domain": "example.com", "subdomain": "mail", "username": "mail@example.com", "user_id": 7, "ips": [], "custom_spf": true, "default": false, "legacy": false, "automatic_security": false, "valid": false, "dns": { "mail_server": { "host": "mail.example.com", "type": "mx", "data": "sendgrid.net", "valid": false }, "subdomain_spf": { "host": "mail.example.com", "type": "txt", "data": "v=spf1 ip4:192.168.1.1 ip4:192.168.0.1 -all", "valid": false }, "domain_spf": { "host": "example.com", "type": "txt", "data": "v=spf1 include:mail.example.com -all", "valid": false }, "dkim": { "host": "s1._domainkey.example.com", "type": "txt", "data": "k=rsa; t=s; p=publicKey", "valid": false } } } } } }, "security": [ { "Authorization": [] } ] } }, "/verified_senders/domains": { "get": { "operationId": "GET_verified_senders-domains", "summary": "Domain Warn List", "tags": [ "Sender Verification" ], "description": "**This endpoint returns a list of domains known to implement DMARC and categorizes them by failure type — hard failure or soft failure**.\n\nDomains listed as hard failures will not deliver mail when used as a [Sender Identity](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/) due to the domain's DMARC policy settings.\n\nFor example, using a `yahoo.com` email address as a Sender Identity will likely result in the rejection of your mail. For more information about DMARC, see [Everything about DMARC](https://sendgrid.com/docs/ui/sending-email/dmarc/).", "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "results": { "type": "object", "required": [ "soft_failures", "hard_failures" ], "properties": { "soft_failures": { "type": "array", "items": { "type": "string" } }, "hard_failures": { "type": "array", "items": { "type": "string" } } } } }, "required": [ "results" ] }, "examples": { "application/json": { "results": { "soft_failures": [ "gmail.com" ], "hard_failures": [ "yahoo.com" ] } } } }, "401": { "$ref": "#/responses/trait:globalErrors:401" }, "403": { "$ref": "#/responses/trait:globalErrors:403" }, "404": { "$ref": "#/responses/trait:globalErrors:404" }, "500": { "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ { "Authorization": [] } ] } }, "/verified_senders/steps_completed": { "get": { "operationId": "GET_verified_senders-steps_completed", "summary": "Completed Steps", "tags": [ "Sender Verification" ], "description": "**This endpoint allows you to determine which of SendGrid’s verification processes have been completed for an account**.\n\nThis endpoint returns boolean values, `true` and `false`, for [Domain Authentication](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/#domain-authentication), `domain_verified`, and [Single Sender Verification](https://sendgrid.com/docs/for-developers/sending-email/sender-identity/#single-sender-verification), `sender_verified`, for the account.\n\nAn account may have one, both, or neither verification steps completed. If you need to authenticate a domain rather than a Single Sender, see the \"Authenticate a domain\" endpoint.", "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "results": { "type": "object", "properties": { "sender_verified": { "type": "boolean" }, "domain_verified": { "type": "boolean" } } } } }, "examples": { "application/json": { "results": { "domain_verified": true, "sender_verified": true } } } }, "401": { "$ref": "#/responses/trait:globalErrors:401" }, "403": { "$ref": "#/responses/trait:globalErrors:403" }, "404": { "$ref": "#/responses/trait:globalErrors:404" }, "500": { "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ { "Authorization": [] } ] } }, "/verified_senders": { "post": { "operationId": "POST_verified_senders", "summary": "Create Verified Sender Request", "tags": [ "Sender Verification" ], "description": "**This endpoint allows you to create a new Sender Identify**.\n\nUpon successful submission of a `POST` request to this endpoint, an identity will be created, and a verification email will be sent to the address assigned to the `from_email` field. You must complete the verification process using the sent email to fully verify the sender.\n\nIf you need to resend the verification email, you can do so with the Resend Verified Sender Request, `/resend/{id}`, endpoint.\n\nIf you need to authenticate a domain rather than a Single Sender, see the [Domain Authentication API](https://sendgrid.api-docs.io/v3.0/domain-authentication/authenticate-a-domain).", "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/verified-sender-request-schema" } } ], "responses": { "201": { "description": "", "schema": { "$ref": "#/definitions/verified-sender-response-schema" }, "examples": { "application/json": { "id": 1234, "nickname": "Example Orders", "from_email": "orders@example.com", "from_name": "Example Orders", "reply_to": "orders@example.com", "reply_to_name": "Example Orders", "address": "1234 Fake St.", "address2": "PO Box 1234", "state": "CA", "city": "San Francisco", "country": "USA", "zip": "94105", "verified": true, "locked": false } } }, "400": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } }, "required": [ "message", "error_id" ] } } }, "required": [ "errors" ] } }, "401": { "$ref": "#/responses/trait:globalErrors:401" }, "403": { "$ref": "#/responses/trait:globalErrors:403" }, "404": { "$ref": "#/responses/trait:globalErrors:404" }, "500": { "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_verified_senders", "summary": "Get All Verified Senders", "tags": [ "Sender Verification" ], "description": "**This endpoint allows you to retrieve all the Sender Identities associated with an account.**\n\nThis endpoint will return both verified and unverified senders.\n\nYou can limit the number of results returned using the `limit`, `lastSeenID`, and `id` query string parameters.\n\n* `limit` allows you to specify an exact number of Sender Identities to return.\n* `lastSeenID` will return senders with an ID number occuring after the passed in ID. In other words, the `lastSeenID` provides a starting point from which SendGrid will iterate to find Sender Identities associated with your account.\n* `id` will return information about only the Sender Identity passed in the request.", "parameters": [ { "name": "limit", "in": "query", "type": "number" }, { "name": "lastSeenID", "in": "query", "type": "number" }, { "name": "id", "in": "query", "type": "integer" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/definitions/verified-sender-response-schema" } } } }, "examples": { "application/json": { "results": [ { "id": 1234, "nickname": "Example Orders", "from_email": "orders@example.com", "from_name": "Example Orders", "reply_to": "orders@example.com", "reply_to_name": "Example Orders", "address": "1234 Fake St.", "address2": "PO Box 1234", "state": "CA", "city": "San Francisco", "country": "USA", "zip": "94105", "verified": true, "locked": false }, { "id": 1235, "nickname": "Example Support", "from_email": "support@example.com", "from_name": "Example Support", "reply_to": "support@example.com", "reply_to_name": "Example Support", "address": "1234 Fake St.", "address2": "PO Box 1234", "state": "CA", "city": "San Francisco", "country": "USA", "zip": "94105", "verified": true, "locked": false } ] } } }, "401": { "$ref": "#/responses/trait:globalErrors:401" }, "403": { "$ref": "#/responses/trait:globalErrors:403" }, "404": { "$ref": "#/responses/trait:globalErrors:404" }, "500": { "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ { "Authorization": [] } ] } }, "/verified_senders/verify/{token}": { "parameters": [ { "name": "token", "in": "path", "required": true, "type": "string" } ], "get": { "operationId": "GET_verified_senders-verify-token", "summary": "Verify Sender Request", "tags": [ "Sender Verification" ], "description": "**This endpoint allows you to verify a sender requests.**\n\nThe token is generated by SendGrid and included in a verification email delivered to the address that's pending verification.", "responses": { "204": { "description": "" }, "401": { "$ref": "#/responses/trait:globalErrors:401" }, "403": { "$ref": "#/responses/trait:globalErrors:403" }, "404": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "error_id": { "type": "string" } }, "required": [ "message", "error_id" ] } } }, "required": [ "errors" ] } }, "500": { "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ { "Authorization": [] } ] } }, "/verified_senders/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "type": "string" } ], "patch": { "operationId": "PATCH_verified_senders-id", "summary": "Edit Verified Sender", "tags": [ "Sender Verification" ], "description": "**This endpoint allows you to update an existing Sender Identity**.\n\nPass the `id` assigned to a Sender Identity to this endpoint as a path parameter. Include any fields you wish to update in the request body in JSON format.\n\nYou can retrieve the IDs associated with Sender Identities by passing a `GET` request to the Get All Verified Senders endpoint, `/verified_senders`.\n\n**Note:** Unlike a `PUT` request, `PATCH` allows you to update only the fields you wish to edit. Fields that are not passed as part of a request will remain unaltered.", "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/verified-sender-request-schema" } } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/verified-sender-response-schema" }, "examples": { "application/json": { "id": 1234, "nickname": "Example Orders", "from_email": "orders@example.com", "from_name": "Example Orders", "reply_to": "orders@example.com", "reply_to_name": "Example Orders", "address": "1234 Fake St.", "address2": "PO Box 1234", "state": "CA", "city": "San Francisco", "country": "USA", "zip": "94105", "verified": true, "locked": false } } }, "400": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } }, "required": [ "message", "error_id" ] } } }, "required": [ "errors" ] } }, "401": { "$ref": "#/responses/trait:globalErrors:401" }, "403": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "error_id": { "type": "string" } }, "required": [ "message", "error_id" ] } } }, "required": [ "errors" ] } }, "404": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "error_id": { "type": "string" } }, "required": [ "message", "error_id" ] } } }, "required": [ "errors" ] } }, "500": { "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_verified_senders-id", "summary": "Delete Verified Sender", "tags": [ "Sender Verification" ], "description": "**This endpoint allows you to delete a Sender Identity**.\n\nPass the `id` assigned to a Sender Identity to this endpoint to delete the Sender Identity from your account.\n\nYou can retrieve the IDs associated with Sender Identities using the \"Get All Verified Senders\" endpoint.", "responses": { "204": { "description": "", "schema": { "type": "object" } }, "401": { "$ref": "#/responses/trait:globalErrors:401" }, "403": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "error_id": { "type": "string" } }, "required": [ "message", "error_id" ] } } } } }, "404": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "error_id": { "type": "string" } }, "required": [ "message", "error_id" ] } } }, "required": [ "errors" ] } }, "500": { "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ { "Authorization": [] } ] } }, "/verified_senders/resend/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "type": "string" } ], "post": { "operationId": "POST_verified_senders-resend-id", "summary": "Resend Verified Sender Request", "tags": [ "Sender Verification" ], "description": "**This endpoint allows you to resend a verification email to a specified Sender Identity**.\n\nPassing the `id` assigned to a Sender Identity to this endpoint will resend a verification email to the `from_address` associated with the Sender Identity. This can be useful if someone loses their verification email or needs to have it resent for any other reason.\n\nYou can retrieve the IDs associated with Sender Identities by passing a \"Get All Verified Senders\" endpoint.", "responses": { "204": { "description": "", "schema": { "type": "object" } }, "400": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "error_id": { "type": "string" } }, "required": [ "message", "error_id" ] } } }, "required": [ "errors" ] } }, "401": { "$ref": "#/responses/trait:globalErrors:401" }, "403": { "$ref": "#/responses/trait:globalErrors:403" }, "404": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" }, "error_id": { "type": "string" } }, "required": [ "message", "error_id" ] } } }, "required": [ "errors" ] } }, "500": { "$ref": "#/responses/trait:globalErrors:500" } }, "security": [ { "Authorization": [] } ] } }, "/designs/{id}": { "parameters": [ { "name": "id", "in": "path", "description": "The ID of the Design you want to duplicate.", "required": true, "type": "string", "format": "uuid" } ], "post": { "operationId": "POST-design", "summary": "Duplicate Design", "tags": [ "Designs API" ], "description": "**This endpoint allows you to duplicate one of your existing designs**.\n\nModifying an existing design is often the easiest way to create something new.\n\nYou are not required to pass any data in the body of a request to this endpoint. If you choose to leave the `name` field blank, your duplicate will be assigned the name of the design it was copied from with the text \"Duplicate: \" prepended to it. This name change is only a convenience, as the duplicate will be assigned a unique ID that differentiates it from your other designs.\n\nYou can modify your duplicate’s name at the time of creation by passing an updated value to the `name` field when making the initial request.\nMore on retrieving design IDs can be found below.", "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/design-duplicate-input", "example": { "name": "Ahoy, Cake or Pie Cafe!", "editor": "design" } } } ], "responses": { "201": { "description": "", "schema": { "$ref": "#/definitions/design-output" }, "examples": { "application/json": { "id": "15b85720-ce48-48ef-8a07-672b0d3455da", "name": "Ahoy, Cake or Pie Cafe!", "html_content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n\n \n
\n
\n \n
| \n
\n \n
\n
\n \n
| \n
\n \n
\n
\n \n
| \n
\n \n
\n
\n \n
| \n
\n \n
\n
\n \n
| \n
\n \n
\n
\n \n
| \n
\n \n
\n
\n \n
| \n
![\"Off](\"https://mc.sendgrid.com/assets/uploads/9d9c1f3d8009c42bbe60c0355f1ed23e86c3f5619173e83a9328b9214e42e1c1d5e009ed5cc4c8f3efedfc33d46bba2f4577b143607025a29add6e89ab4662ad.png\")
![\"\"](\"https://mc.sendgrid.com/assets/uploads/e324b295c47223f1a936198fbd4e5d4b239ff86c6d6c89d4d0eb8d7c61028921abfc4901ba607f6dcb7acc7067bb0c6df4313726b14b8274e0b2c98cdf8b58d2.png\")
![\"\"](\"https://mc.sendgrid.com/assets/uploads/0accac77b1e34c614730ab732317a493478835c96bd549fb2df7a921ec1177fdb30d6d33e1d0a33d8c6c579344890ae408ce13aaed0e478f1fd6d2219d308365.png\")
![\"Facebook\"](\"https://mc.sendgrid.com/assets/social/white/facebook.png\" "\\"Facebook\\"")
\n ![\"Twitter\"](\"https://mc.sendgrid.com/assets/social/white/twitter.png\" "\\"Twitter\\"")
\n ![\"Instagram\"](\"https://mc.sendgrid.com/assets/social/white/instagram.png\" "\\"Instagram\\"")
\n ![\"Pinterest\"](\"https://mc.sendgrid.com/assets/social/white/pinterest.png\" "\\"Pinterest\\"")
\n \n \n
\n
\n \n
| \n