<% 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
\n Search using segment conditions without actually creating a segment.\n Body contains a JSON object with conditions, a list of conditions as described below, and an optional list_id, which is a valid list ID for a list to limit the search on.\n
\n Valid operators for create and update depend on the type of the field for which you are searching.\n
\n\n- \n
- Dates:\n
- \n
- \"eq\", \"ne\", \"lt\" (before), \"gt\" (after)\n
- \n
- You may use MM/DD/YYYY for day granularity or an epoch for second granularity. \n
\n - \"empty\", \"not_empty\" \n
- \"is within\"\n
- \n
- You may use an ISO 8601 date format or the # of days. \n
\n
\n - \"eq\", \"ne\", \"lt\" (before), \"gt\" (after)\n
- Text: \"contains\", \"eq\" (is - matches the full field), \"ne\" (is not - matches any field where the entire field is not the condition value), \"empty\", \"not_empty\" \n
- Numbers: \"eq\", \"lt\", \"gt\", \"empty\", \"not_empty\" \n
- Email Clicks and Opens: \"eq\" (opened), \"ne\" (not opened) \n
\n Field values must all be a string.\n
\n\n\n Search conditions using \"eq\" or \"ne\" for email clicks and opens should provide a \"field\" of either clicks.campaign_identifier or opens.campaign_identifier.\n The condition value should be a string containing the id of a completed campaign.\n
\n Search conditions list may contain multiple conditions, joined by an \"and\" or \"or\" in the \"and_or\" field.\n The first condition in the conditions list must have an empty \"and_or\", and subsequent conditions must all specify an \"and_or\".\n
", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "list_id": { "type": "integer", "format": "int32" }, "conditions": { "type": "array", "items": { "and_or": "", "field": "birthday", "value": "01/12/1985", "operator": "eq" } } }, "required": [ "list_id", "conditions" ], "example": { "list_id": -27497588, "conditions": [ { "and_or": "", "field": "birthday", "value": "01/12/1985", "operator": "eq" }, { "and_or": "", "field": "birthday", "value": "01/12/1985", "operator": "eq" }, { "and_or": "", "field": "birthday", "value": "01/12/1985", "operator": "eq" }, { "and_or": "", "field": "birthday", "value": "01/12/1985", "operator": "eq" } ] } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "recipients": { "type": "array", "items": { "type": "object", "properties": { "created_at": { "type": "integer" }, "email": { "type": "string" }, "id": { "type": "string" }, "last_emailed": { "type": "integer" }, "last_clicked": { "type": "integer" }, "last_opened": { "type": "integer" }, "custom_fields": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "value": { "anyOf": [ { "type": "integer" }, { "type": "string" } ] }, "type": { "type": "string" } } } }, "updated_at": { "type": "integer" }, "first_name": { "type": "string" } } } }, "recipient_count": { "type": "integer" } } }, "examples": { "application/json": { "recipients": [ { "created_at": -27901208, "email": "ut magna quis ipsum", "id": "fugiat ad adipisicing ullamco", "last_emailed": 21626657 }, { "created_at": 17466400, "email": "sunt irure", "id": "et", "last_clicked": -23135244, "last_opened": -44593357, "first_name": "est" }, { "created_at": -34495329, "email": "reprehenderit incididunt velit Lorem esse", "id": "esse Ut ad dolore", "last_clicked": 10164083, "last_opened": 34443062 }, { "created_at": -37030673, "email": "amet deserunt fugiat voluptate", "id": "et exercitation commodo id laborum", "last_clicked": -10497425 }, { "created_at": 3658435, "email": "labore veniam", "id": "ad pariatur esse", "last_opened": -84227501, "custom_fields": [ { "id": -5765608, "name": "proident pariatur", "value": "do in magna mollit", "type": "dolore ut" }, { "id": -31131201, "name": "laborum mollit", "value": 84434696, "type": "veniam" } ], "updated_at": -56455352, "first_name": "Ut cupidatat nulla deserunt adipisicing", "last_clicked": -52862671 } ], "recipient_count": 65190677 } } }, "400": { "description": "" } }, "security": [ { "Authorization": [] } ] } }, "/contactdb/custom_fields": { "post": { "operationId": "POST_contactdb-custom_fields", "summary": "Create a Custom Field", "tags": [ "Contacts API - Custom Fields" ], "description": "**This endpoint allows you to create a custom field.**\n\n**You can create up to 120 custom fields.**", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } }, "example": { "name": "pet", "type": "text" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "201": { "description": "", "schema": { "$ref": "#/definitions/contactdb_custom_field_with_id" }, "examples": { "application/json": { "id": 1, "name": "pet", "type": "text" } } }, "400": { "description": "\"\" : \"Returned if request body is invalid JSON\"\n\"type\" : \"Returned if custom field type is invalid or not provided\"\n\"name\" : \"Returned if custom field name is not provided\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "Returned if request body is invalid JSON" }, { "field": "type", "message": "Returned if custom field type is invalid or not provided" }, { "field": "name", "message": "Returned if custom field name is not provided" } ] } } } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_contactdb-custom_fields", "summary": "Retrieve all custom fields", "tags": [ "Contacts API - Custom Fields" ], "description": "**This endpoint allows you to retrieve all custom fields.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "title": "List All Custom Fields response", "type": "object", "properties": { "custom_fields": { "type": "array", "items": { "$ref": "#/definitions/contactdb_custom_field_with_id" } } }, "required": [ "custom_fields" ] }, "examples": { "application/json": { "custom_fields": [ { "id": 6234, "name": "age", "type": "number" }, { "id": 6233, "name": "country", "type": "text" }, { "id": 6235, "name": "favorite_color", "type": "text" }, { "id": 6239, "name": "fname", "type": "text" }, { "id": 6240, "name": "lname", "type": "text" }, { "id": 49439, "name": "pet", "type": "text" } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/contactdb/custom_fields/{custom_field_id}": { "parameters": [ { "name": "custom_field_id", "in": "path", "description": "The ID of the custom field that you want to retrieve.", "required": true, "type": "integer" } ], "get": { "operationId": "GET_contactdb-custom_fields-custom_field_id", "summary": "Retrieve a Custom Field", "tags": [ "Contacts API - Custom Fields" ], "description": "**This endpoint allows you to retrieve a custom field by ID.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/contactdb_custom_field_with_id" }, "examples": { "application/json": { "id": 1, "name": "pet", "type": "text" } } }, "400": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "message": "invalid id" } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } }, "404": { "description": "\"custom_field_id\" : \"Returned if custom_field_id does not exist\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "message": "Custom field ID does not exist" } ] } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_contactdb-custom_fields-custom_field_id", "summary": "Delete a Custom Field", "tags": [ "Contacts API - Custom Fields" ], "description": "**This endpoint allows you to delete a custom field by ID.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "202": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "message": "Custom Field delete is processing." } } }, "400": { "description": "\"id\" : \"Returned if custom_field_id is not valid\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "message": "Custom field in use by one or more segment conditions" }, { "message": "Custom field ID does not exist" } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } }, "404": { "description": "\"custom_field_id\" : \"Returned if custom_field_id does not exist\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "message": "Custom field ID does not exist" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/contactdb/reserved_fields": { "get": { "operationId": "GET_contactdb-reserved_fields", "summary": "Retrieve reserved fields", "tags": [ "Contacts API - Custom Fields" ], "description": "**This endpoint allows you to list all fields that are reserved and can't be used for custom field names.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "reserved_fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" } } } } } }, "examples": { "application/json": { "reserved_fields": [ { "name": "first_name", "type": "text" }, { "name": "last_name", "type": "text" }, { "name": "email", "type": "text" }, { "name": "created_at", "type": "date" }, { "name": "updated_at", "type": "date" }, { "name": "last_emailed", "type": "date" }, { "name": "last_clicked", "type": "date" }, { "name": "last_opened", "type": "date" }, { "name": "lists", "type": "set" }, { "name": "campaigns", "type": "set" }, { "name": "my_custom_field", "type": "text" } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/contactdb/segments": { "post": { "operationId": "POST_contactdb-segments", "summary": "Create a Segment", "tags": [ "Contacts API - Segments" ], "description": "**This endpoint allows you to create a new segment.**\n\n\n Valid operators for create and update depend on the type of the field for which you are searching.\n\n**Dates**\n- \"eq\", \"ne\", \"lt\" (before), \"gt\" (after)\n - You may use MM/DD/YYYY for day granularity or an epoch for second granularity.\n- \"empty\", \"not_empty\"\n- \"is within\"\n - You may use an [ISO 8601 date format](https://en.wikipedia.org/wiki/ISO_8601) or the # of days.\n\n**Text**\n- \"contains\"\n- \"eq\" (is/equals - matches the full field)\n- \"ne\" (is not/not equals - matches any field where the entire field is not the condition value)\n- \"empty\"\n- \"not_empty\"\n\n**Numbers**\n- \"eq\" (is/equals)\n- \"lt\" (is less than)\n- \"gt\" (is greater than)\n- \"empty\"\n- \"not_empty\"\n\n**Email Clicks and Opens**\n- \"eq\" (opened)\n- \"ne\" (not opened)\n\nAll field values must be a string.\n\n\nConditions using \"eq\" or \"ne\" for email clicks and opens should provide a \"field\" of either `clicks.campaign_identifier` or `opens.campaign_identifier`.\nThe condition value should be a string containing the id of a completed campaign.\n\n\nThe conditions list may contain multiple conditions, joined by an \"and\" or \"or\" in the \"and_or\" field.\n\nThe first condition in the conditions list must have an empty \"and_or\", and subsequent conditions must all specify an \"and_or\".", "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/contactdb_segments", "example": { "name": "Last Name Miller", "list_id": 4, "conditions": [ { "field": "last_name", "value": "Miller", "operator": "eq", "and_or": "" }, { "field": "last_clicked", "value": "01/02/2015", "operator": "gt", "and_or": "and" }, { "field": "clicks.campaign_identifier", "value": "513", "operator": "eq", "and_or": "or" } ] } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/contactdb_segments_with_id" }, "examples": { "application/json": { "id": 1, "name": "Last Name Miller", "list_id": 4, "conditions": [ { "field": "last_name", "value": "Miller", "operator": "eq", "and_or": "" }, { "field": "last_clicked", "value": "01/02/2015", "operator": "gt", "and_or": "and" }, { "field": "clicks.campaign_identifier", "value": "513", "operator": "eq", "and_or": "or" } ], "recipient_count": 0 } } }, "400": { "description": "\"name\" : \"Returned if the name is not valid\"\n\"list_id\" : \"Returned if the list_id is not valid\"\n\"and_or\" : \"Returned if and_or and set value is not passed into the request body\"\n\"and_or\" : \"Returned if and_or is set on the only condition passed\"\n\"and_or\" : \"Returned if and_or is set on all conditions\"\n\"and_or\" : \"Returned if and_or is not set on more than one condition and less than all conditions\"\n\"operator\" : \"Returned if operator and set value is not passed into the request body\"\n\"value\" : \"Returned if value and set value is not passed into the request body\"\n\"field\" : \"Returned if field and set value is not passed into the request body\"\n\"\" : \"Returned if request body is not valid json\"\n\"\" : \"Returned if invalid value is passed into one of the request body parameters\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "message": "request body is not valid json" }, { "message": "invalid value is passed into one of the request body parameters" }, { "field": "field", "message": "field and set value is not passed into the request body" }, { "field": "value", "message": "value and set value is not passed into the request body" }, { "field": "operator", "message": "operator and set value is not passed into the request body" }, { "field": "and_or", "message": "and_or is not set on more than one condition and less than all conditions" }, { "field": "and_or", "message": "and_or is set on all conditions" }, { "field": "and_or", "message": "and_or is set on the only condition passed" }, { "field": "and_or", "message": "and_or and set value is not passed into the request body" }, { "field": "list_id", "message": "the list_id is not valid" }, { "field": "name", "message": "the name is not valid" } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_contactdb-segments", "summary": "Retrieve all segments", "tags": [ "Contacts API - Segments" ], "description": "**This endpoint allows you to retrieve all of your segments.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "title": "List All Segments response", "type": "object", "properties": { "segments": { "type": "array", "items": { "$ref": "#/definitions/contactdb_segments" } } }, "required": [ "segments" ] }, "examples": { "application/json": { "segments": [ { "id": 1234, "name": "Age segments < 25", "conditions": [ { "field": "age", "value": "25", "operator": "lt" } ], "recipient_count": 8 }, { "id": 2345, "name": "email address - gmail", "conditions": [ { "field": "email", "value": "@gmail.com", "operator": "contains" } ], "recipient_count": 0 } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/contactdb/segments/{segment_id}": { "parameters": [ { "name": "segment_id", "in": "path", "required": true, "type": "string" } ], "get": { "operationId": "GET_contactdb-segments-segment_id", "summary": "Retrieve a segment", "tags": [ "Contacts API - Segments" ], "description": "**This endpoint allows you to retrieve a single segment with the given ID.**", "parameters": [ { "name": "segment_id", "in": "query", "description": "The ID of the segment you want to request.", "required": true, "type": "integer" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/contactdb_segments" }, "examples": { "application/json": { "id": 1, "name": "Last Name Miller", "list_id": 4, "conditions": [ { "field": "last_name", "value": "Miller", "operator": "eq", "and_or": "" } ], "recipient_count": 1 } } }, "400": { "description": "\"segment_id\" : \"Returned if segment_id is not valid\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "message": "if segment_id is not valid" } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } }, "404": { "description": "\"segment_id\" : \"Returned if segment_id does not exist\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "message": "segment_id not found" } ] } } } }, "security": [ { "Authorization": [] } ] }, "patch": { "operationId": "PATCH_contactdb-segments-segment_id", "summary": "Update a segment", "tags": [ "Contacts API - Segments" ], "description": "**This endpoint allows you to update a segment.**", "parameters": [ { "name": "segment_id", "in": "query", "description": "The ID of the segment you are updating.", "type": "string" }, { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "name": { "type": "string" }, "list_id": { "type": "number", "description": "The list ID you would like this segment to be built from." }, "conditions": { "type": "array", "description": "The conditions by which this segment should be created.", "items": { "$ref": "#/definitions/contactdb_segments_conditions" } } }, "required": [ "name" ], "example": { "name": "The Millers", "list_id": 5, "conditions": [ { "field": "last_name", "value": "Miller", "operator": "eq", "and_or": "" } ] } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/contactdb_segments" }, "examples": { "application/json": { "id": 5, "name": "The Millers", "list_id": 5, "conditions": [ { "field": "last_name", "value": "Miller", "operator": "eq", "and_or": "" } ], "recipient_count": 1 } } }, "400": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "message": "request body is not valid json" }, { "message": "invalid value is passed into one of the request body parameters" }, { "segment_id": "segment_id", "message": "segment id is not valid" }, { "field": "field", "message": "field and set value is not passed into the request body" }, { "field": "value", "message": "value and set value is not passed into the request body" }, { "field": "operator", "message": "operator and set value is not passed into the request body" }, { "field": "and_or", "message": "and_or is not set on more than one condition and less than all conditions" }, { "field": "and_or", "message": "and_or is set on all conditions" }, { "field": "and_or", "message": "and_or is set on the only condition passed" }, { "field": "and_or", "message": "and_or and set value is not passed into the request body" }, { "field": "list_id", "message": "the list_id is not valid" }, { "field": "name", "message": "the name is not valid" } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_contactdb-segments-segment_id", "summary": "Delete a segment", "tags": [ "Contacts API - Segments" ], "description": "**This endpoint allows you to delete a segment from your recipients database.**\n\nYou also have the option to delete all the contacts from your Marketing Campaigns recipient database who were in this segment.", "parameters": [ { "name": "delete_contacts", "in": "query", "description": "True to delete all contacts matching the segment in addition to deleting the segment", "type": "boolean" }, { "name": "body", "in": "body", "schema": { "type": "null" } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "204": { "description": "", "schema": { "type": "null" } }, "400": { "description": "\"segment_id\" : \"Returned if segment_id is not valid\"\n\"delete_contacts\" : \"Returned if delete_contacts is not a valid boolean\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": "segment_id", "message": "Returned if segment_id is not valid" }, { "field": "delete_contacts", "message": "Returned if delete_contacts is not a valid boolean" } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } }, "404": { "description": "\"segment_id\" : \"Returned if segment_id does not exist\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": "segment_id", "message": "segment_id does not exist" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/contactdb/segments/{segment_id}/recipients": { "parameters": [ { "name": "segment_id", "in": "path", "description": "The ID of the segment from which you want to retrieve recipients.", "required": true, "type": "integer" } ], "get": { "operationId": "GET_contactdb-segments-segment_id-recipients", "summary": "Retrieve recipients on a segment", "tags": [ "Contacts API - Segments" ], "description": "**This endpoint allows you to retrieve all of the recipients in a segment with the given ID.**", "parameters": [ { "name": "page", "in": "query", "type": "integer" }, { "name": "page_size", "in": "query", "type": "integer" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "title": "List Recipients On a Segment response", "type": "object", "properties": { "recipients": { "type": "array", "items": { "$ref": "#/definitions/contactdb_recipient" } } }, "required": [ "recipients" ] }, "examples": { "application/json": { "recipients": [ { "created_at": 1422313607, "email": "jones@example.com", "first_name": null, "id": "YUBh", "last_clicked": null, "last_emailed": null, "last_name": "Jones", "last_opened": null, "updated_at": 1422313790, "custom_fields": [ { "id": 23, "name": "pet", "value": "Indiana", "type": "text" } ] } ] } } }, "400": { "description": "\"page\" : \"Returned if page is not a valid integer\"\n\"page\" : \"Returned if page is less than 1\"\n\"page_size\" : \"Returned if page_size is not a valid integer\"", "schema": { "type": "object" } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } }, "404": { "description": "\"segment_id\" : \"Returned if segment_id is not valid\"\n\"segment_id\" : \"Returned if segment_id does not exist\"", "schema": { "type": "object" } } }, "security": [ { "Authorization": [] } ] } }, "/categories": { "get": { "operationId": "GET_categories", "summary": "Retrieve all categories", "tags": [ "Categories" ], "description": "**This endpoint allows you to retrieve a list of all of your categories.**", "parameters": [ { "name": "limit", "in": "query", "description": "The number of categories to display per page.", "type": "integer", "default": 50 }, { "name": "category", "in": "query", "description": "Allows you to perform a prefix search on this particular category.", "type": "string" }, { "name": "offset", "in": "query", "description": "The point in the list that you would like to begin displaying results.", "type": "integer", "default": 0 }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "array", "items": { "type": "object", "properties": { "category": { "type": "string", "description": "A category used to group emails by broad topic." } }, "required": [ "category" ] } }, "examples": { "application/json": [ { "category": "category 1" }, { "category": "category 2" } ] } }, "400": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "description": "The error returned.", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string", "description": "A message explaining why your categories could not be retrieved." } }, "required": [ "field", "message" ] } } } }, "examples": { "application/json": { "errors": [ { "field": "sort_by", "message": "invalid sort value" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/categories/stats/sums": { "get": { "operationId": "GET_categories-stats-sums", "summary": "Retrieve sums of email stats for each category [Needs: Stats object defined, has category ID?]", "tags": [ "Categories" ], "description": "**This endpoint allows you to retrieve the total sum of each email statistic for every category over the given date range.**\n\nIf you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.", "parameters": [ { "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" }, { "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.", "required": false, "type": "integer", "default": 5 }, { "name": "offset", "in": "query", "description": "The point in the list to begin retrieving results.", "required": false, "type": "integer", "default": 0 }, { "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" ] }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/category_stats" }, "examples": { "application/json": { "date": "2015-01-01", "stats": [ { "metrics": { "blocks": 0, "bounce_drops": 0, "bounces": 0, "clicks": 20, "deferred": 0, "delivered": 20, "invalid_emails": 0, "opens": 20, "processed": 0, "requests": 20, "spam_report_drops": 0, "spam_reports": 0, "unique_clicks": 20, "unique_opens": 20, "unsubscribe_drops": 0, "unsubscribes": 20 }, "name": "cat1", "type": "category" }, { "metrics": { "blocks": 1, "bounce_drops": 0, "bounces": 0, "clicks": 19, "deferred": 0, "delivered": 19, "invalid_emails": 0, "opens": 19, "processed": 0, "requests": 20, "spam_report_drops": 0, "spam_reports": 0, "unique_clicks": 19, "unique_opens": 19, "unsubscribe_drops": 0, "unsubscribes": 19 }, "name": "cat2", "type": "category" }, { "metrics": { "blocks": 0, "bounce_drops": 0, "bounces": 0, "clicks": 5, "deferred": 0, "delivered": 5, "invalid_emails": 0, "opens": 5, "processed": 0, "requests": 5, "spam_report_drops": 0, "spam_reports": 0, "unique_clicks": 5, "unique_opens": 5, "unsubscribe_drops": 0, "unsubscribes": 5 }, "name": "cat3", "type": "category" }, { "metrics": { "blocks": 0, "bounce_drops": 0, "bounces": 0, "clicks": 6, "deferred": 0, "delivered": 5, "invalid_emails": 0, "opens": 6, "processed": 0, "requests": 5, "spam_report_drops": 0, "spam_reports": 0, "unique_clicks": 5, "unique_opens": 5, "unsubscribe_drops": 0, "unsubscribes": 6 }, "name": "cat4", "type": "category" }, { "metrics": { "blocks": 10, "bounce_drops": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "invalid_emails": 0, "opens": 0, "processed": 0, "requests": 10, "spam_report_drops": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0, "unsubscribe_drops": 0, "unsubscribes": 0 }, "name": "cat5", "type": "category" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/categories/stats": { "get": { "operationId": "GET_categories-stats", "summary": "Retrieve Email Statistics for Categories", "tags": [ "Categories" ], "description": "**This endpoint allows you to retrieve all of your email statistics for each of your categories.**\n\nIf you do not define any query parameters, this endpoint will return a sum for each category in groups of 10.", "parameters": [ { "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": "categories", "in": "query", "description": "The individual categories that you want to retrieve statistics for. You may include up to 10 different categories.", "required": true, "type": "string" }, { "name": "limit", "in": "query", "description": "The number of results to include.", "required": false, "type": "integer", "default": 500, "maximum": 500 }, { "name": "offset", "in": "query", "description": "The number of results to skip.", "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" ] }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "array", "items": { "$ref": "#/definitions/category_stats" } }, "examples": { "application/json": [ { "date": "2015-10-01", "stats": [ { "type": "category", "name": "docs", "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 } }, { "type": "category", "name": "mattscategory", "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-11-01", "stats": [ { "type": "category", "name": "docs", "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 } }, { "type": "category", "name": "mattscategory", "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": [] } ] } }, "/campaigns": { "post": { "operationId": "POST_campaigns", "summary": "Create a Campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to create a campaign.**\n\nIn order to send or schedule the campaign, you will be required to provide a subject, sender ID, content (we suggest both html and plain text), and at least one list or segment ID. This information is not required when you create a campaign.", "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/campaign_request", "example": { "title": "March Newsletter", "subject": "New Products for Spring!", "sender_id": 124451, "list_ids": [ 110, 124 ], "segment_ids": [ 110 ], "categories": [ "spring line" ], "suppression_group_id": 42, "custom_unsubscribe_url": "", "ip_pool": "marketing", "html_content": "Check out our spring line!
", "plain_content": "Check out our spring line!" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "201": { "description": "", "schema": { "$ref": "#/definitions/campaign_response" }, "examples": { "application/json": { "id": 986724, "title": "March Newsletter", "subject": "New Products for Spring!", "sender_id": 124451, "list_ids": [ 110, 124 ], "segment_ids": [ 110 ], "categories": [ "spring line" ], "suppression_group_id": 42, "custom_unsubscribe_url": "", "ip_pool": "marketing", "html_content": "Check out our spring line!
", "plain_content": "Check out our spring line!", "status": "Draft" } } }, "400": { "description": "\"title\": \"title can't be blank\"\n\"title\": \"title is too long (maximum is 100 characters)\"\n\"categories\": \"categories exceeds 10 category limit\"\n\"html_content\": \"html_content exceeds the 1MB limit\"\n\"plain_content\": \"plain_content exceeds the 1MB limit\"\n\"sender_id\": \"sender_id does not exist\"\n\"sender_id\": \"sender_id is not a verified sender identity\"\n\"list_ids\": \"list_ids do not all exist\"\n\"segment_ids\": \"segment_ids do not all exist\"\n\"ip_pool\": \"The ip pool you provided is invalid\"\n\"suppression_group_id\": \"suppression_group_id does not exist\"\n\"unsubscribes\": \"Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"\n\"\": \"You've reached your limit of 250 campaigns. Please delete one or more and try again.\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": "title", "message": "title can't be blank" }, { "field": "title", "message": "title is too long (maximum is 100 characters)" }, { "field": "categories", "message": "categories exceeds 10 category limit" }, { "field": "html_content", "message": "html_content exceeds the 1MB limit" }, { "field": "plain_content", "message": "plain_content exceeds the 1MB limit" }, { "field": "sender_id", "message": "sender_id does not exist" }, { "field": "sender_id", "message": "sender_id is not a verified sender identity" }, { "field": "list_ids", "message": "list_ids do not all exist" }, { "field": "segment_ids", "message": "segment_ids do not all exist" }, { "field": "ip_pool", "message": "The ip pool you provided is invalid" }, { "field": "suppression_group_id", "message": "suppression_group_id does not exist" }, { "field": "unsubscribes", "message": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." }, { "field": null, "message": "The JSON you have submitted cannot be parsed." }, { "field": null, "message": "You've reached your limit of 250 campaigns. Please delete one or more and try again." } ] } } }, "401": { "description": "", "schema": { "type": "object" } } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_campaigns", "summary": "Retrieve all Campaigns", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to retrieve a list of all of your campaigns.**\n\nReturns campaigns in reverse order they were created (newest first).\n\nReturns an empty array if no campaigns exist.", "parameters": [ { "name": "limit", "in": "query", "description": "The number of results you would like to receive at a time.", "type": "integer", "default": 10 }, { "name": "offset", "in": "query", "description": "The index of the first campaign to return, where 0 is the first campaign.", "type": "integer", "default": 0 }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/definitions/campaign_response" } } } }, "examples": { "application/json": { "result": [ { "id": 986724, "title": "March Newsletter", "subject": "New Products for Spring!", "sender_id": 124451, "list_ids": [ 110, 124 ], "segment_ids": [ 110 ], "categories": [ "spring line" ], "suppression_group_id": 42, "custom_unsubscribe_url": "", "ip_pool": "marketing", "html_content": "Check out our spring line!
", "plain_content": "Check out our spring line!", "status": "Draft" }, { "id": 986723, "title": "February Newsletter", "subject": "Final Winter Product Sale!", "sender_id": 124451, "list_ids": [ 110, 124 ], "segment_ids": [ 110 ], "categories": [ "winter line" ], "suppression_group_id": 42, "custom_unsubscribe_url": "", "ip_pool": "marketing", "html_content": "Last call for winter clothes!
", "plain_content": "Last call for winter clothes!", "status": "Sent" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/campaigns/{campaign_id}": { "parameters": [ { "name": "campaign_id", "in": "path", "description": "The id of the campaign you would like to retrieve.", "required": true, "type": "integer" } ], "get": { "operationId": "GET_campaigns-campaign_id", "summary": "Retrieve a single campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to retrieve a specific campaign.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "categories": { "type": "array", "items": { "type": "string" } }, "custom_unsubscribe_url": { "type": "string" }, "html_content": { "type": "string" }, "id": { "type": "integer" }, "ip_pool": { "type": "string" }, "list_ids": { "type": "array", "items": { "type": "integer" } }, "plain_content": { "type": "string" }, "segment_ids": { "type": "array", "items": { "type": "integer" } }, "sender_id": { "type": "integer" }, "status": { "type": "string" }, "subject": { "type": "string" }, "suppression_group_id": { "type": "integer" }, "title": { "type": "string" } } }, "examples": { "application/json": { "categories": [ "spring line" ], "custom_unsubscribe_url": "", "html_content": "Check out our spring line!
", "id": 986724, "ip_pool": "marketing", "list_ids": [ 110 ], "plain_content": "Check out our spring line!", "segment_ids": [ 110 ], "sender_id": 124451, "status": "Draft", "subject": "New Products for Spring!", "suppression_group_id": 42, "title": "March Newsletter" } } }, "401": { "description": "", "schema": { "type": "object" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } }, "404": { "description": "\"\": \"not found\"", "schema": { "type": "object" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "not found" } ] } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_campaigns-campaign_id", "summary": "Delete a Campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to delete a specific campaign.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "204": { "description": "", "schema": { "type": "null" } }, "401": { "description": "", "schema": { "type": "object" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } }, "404": { "description": "\"\": \"not found\"", "schema": { "type": "object" } } }, "security": [ { "Authorization": [] } ] }, "patch": { "operationId": "PATCH_campaigns-campaign_id", "summary": "Update a Campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to update a specific campaign.**\n\nThis is especially useful if you only set up the campaign using POST /campaigns, but didn't set many of the parameters.", "parameters": [ { "name": "body", "in": "body", "schema": { "title": "Update a Campaign request", "type": "object", "properties": { "title": { "type": "string", "description": "The title of the campaign." }, "subject": { "type": "string", "description": "The subject line for your campaign." }, "categories": { "type": "array", "description": "The categories you want to tag on this campaign.", "items": { "type": "string" } }, "html_content": { "type": "string", "description": "The HTML content of this campaign." }, "plain_content": { "type": "string", "description": "The plain content of this campaign." } }, "required": [ "title", "subject", "categories", "html_content", "plain_content" ], "example": { "title": "May Newsletter", "subject": "New Products for Summer!", "categories": [ "summer line" ], "html_content": "Check out our summer line!
", "plain_content": "Check out our summer line!" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/campaign_response" }, "examples": { "application/json": { "id": 986724, "title": "May Newsletter", "subject": "New Products for Summer!", "sender_id": 124451, "list_ids": [ 110, 124 ], "segment_ids": [ 110 ], "categories": [ "summer line" ], "suppression_group_id": 42, "custom_unsubscribe_url": "", "ip_pool": "marketing", "html_content": "Check out our summer line!
", "plain_content": "Check out our summer line!", "status": "Draft" } } }, "400": { "description": "\"title\": \"title can't be blank\"\n\"title\": \"title is too long (maximum is 100 characters)\"\n\"categories\": \"categories exceeds 10 category limit\"\n\"html_content\": \"html_content exceeds the 1MB limit\"\n\"plain_content\": \"plain_content exceeds the 1MB limit\"\n\"sender_id\": \"sender_id does not exist\"\n\"sender_id\": \"sender_id is not a verified sender identity\"\n\"list_ids\": \"list_ids do not all exist\"\n\"segment_ids\": \"segment_ids do not all exist\"\n\"ip_pool\": \"The ip pool you provided is invalid\"\n\"suppression_group_id\": \"suppression_group_id does not exist\"\n\"unsubscribes\": \"Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"", "schema": { "type": "object" }, "examples": { "application/json": { "errors": [ { "field": "title", "message": "title can't be blank" }, { "field": "title", "message": "title is too long (maximum is 100 characters)" }, { "field": "categories", "message": "categories exceeds 10 category limit" }, { "field": "html_content", "message": "html_content exceeds the 1MB limit" }, { "field": "plain_content", "message": "plain_content exceeds the 1MB limit" }, { "field": "sender_id", "message": "sender_id does not exist" }, { "field": "sender_id", "message": "sender_id is not a verified sender identity" }, { "field": "list_ids", "message": "list_ids do not all exist" }, { "field": "segment_ids", "message": "segment_ids do not all exist" }, { "field": "ip_pool", "message": "The ip pool you provided is invalid" }, { "field": "suppression_group_id", "message": "suppression_group_id does not exist" }, { "field": "unsubscribes", "message": "Either suppression_group_id or custom_unsubscribe_url may be set/used, but not both. Please remove one before setting the other." }, { "field": null, "message": "The JSON you have submitted cannot be parsed." } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } }, "403": { "description": "\"\": \"You may only update a campaign when it is in draft mode.\"", "schema": { "type": "object" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "You may only update a campaign when it is in draft mode." } ] } } }, "404": { "description": "\"\": \"not found\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "not found" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/campaigns/{campaign_id}/schedules/now": { "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "type": "integer" } ], "post": { "operationId": "POST_campaigns-campaign_id-schedules-now", "summary": "Send a Campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to immediately send an existing campaign.**\n\nNormally a POST request would have a body, but since this endpoint is telling us to send a resource that is already created, a request body is not needed.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "201": { "description": "", "schema": { "title": "Send a Campaign response", "type": "object", "properties": { "id": { "type": "integer", "format": "int64" }, "status": { "type": "string" } }, "required": [ "id", "status" ] }, "examples": { "application/json": { "id": 1234, "status": "Scheduled" } } }, "400": { "description": "\"subject\": \"subject can't be blank\"\n\"sender_id\": \"sender_id can't be blank\"\n\"plain_content\": \"plain_content can't be blank, please provide plain text or html content\"\n\"list_ids\": \"You must select at least 1 segment or 1 list to send to.\"\n\"unsubscribe_tag\": \"An [unsubscribe] tag in both your html and plain content is required to send a campaign.\"\n\"suppression_group_id\": \"Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign.\"\n\"\": \"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": "subject", "message": "subject can't be blank" }, { "field": "sender_id", "message": "sender_id can't be blank" }, { "field": "plain_content", "message": "plain_content can't be blank, please provide plain text or html content" }, { "field": "list_id", "message": "You must select at least 1 segment or 1 list to send to." }, { "field": "unsubscribe_tag", "message": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." }, { "field": "suppression_group_id", "message": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." }, { "field": null, "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } }, "403": { "description": "\"\": \"You may only send a campaign when it is in draft mode.\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "You may only send a campaign when it is in draft mode." } ] } } }, "404": { "description": "\"\": \"not found\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "not found" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/campaigns/{campaign_id}/schedules": { "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "type": "integer" } ], "post": { "operationId": "POST_campaigns-campaign_id-schedules", "summary": "Schedule a Campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to schedule a specific date and time for your campaign to be sent.**\n\nIf you have the flexibility, it's better to schedule mail for off-peak times. Most emails are scheduled and sent at the top of the hour or half hour. Scheduling email to avoid those times (for example, scheduling at 10:53) can result in lower deferral rates because it won't be going through our servers at the same times as everyone else's mail.", "parameters": [ { "name": "body", "in": "body", "schema": { "title": "Schedule a Campaign request", "type": "object", "properties": { "send_at": { "type": "integer", "description": "The unix timestamp for the date and time you would like your campaign to be sent out." } }, "required": [ "send_at" ], "example": { "send_at": 1489771528 } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "201": { "description": "", "schema": { "title": "Schedule a Campaign response", "type": "object", "properties": { "id": { "type": "integer", "description": "The campaign ID." }, "send_at": { "type": "integer", "description": "The date time you scheduled your campaign to be sent." }, "status": { "type": "string", "description": "The status of your campaign.", "enum": [ "Scheduled" ] } }, "required": [ "id", "send_at", "status" ] }, "examples": { "application/json": { "id": 1234, "send_at": 1489771528, "status": "Scheduled" } } }, "400": { "description": "\"subject\": \"subject can't be blank\"\n\"sender_id\": \"sender_id can't be blank\"\n\"plain_content\": \"plain_content can't be blank, please provide plain text or html content\"\n\"list_ids\": \"You must select at least 1 segment or 1 list to send to.\"\n\"send_at\": \"Please choose a future time for sending your campaign.\"\n\"unsubscribe_tag\": \"An [unsubscribe] tag in both your html and plain content is required to send a campaign.\"\n\"suppression_group_id\": \"Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign.\"\n\"\": \"The JSON you have submitted cannot be parsed.\"\n\"\":\"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": "subject", "message": "subject can't be blank" }, { "field": "sender_id", "message": "sender_id can't be blank" }, { "field": "plain_content", "message": "plain_content can't be blank, please provide plain text or html content" }, { "field": "list_id", "message": "You must select at least 1 segment or 1 list to send to." }, { "field": "unsubscribe_tag", "message": "An [unsubscribe] tag in both your html and plain content is required to send a campaign." }, { "field": "suppression_group_id", "message": "Either a suppression_group_id or custom_unsubscribe_url is required to send a campaign." }, { "field": null, "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" } ] } } }, "401": { "description": "", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "authorization required" } ] } } }, "403": { "description": "\"\": \"You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH.\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "You cannot POST to a campaign that has already sent or scheduled. However you can update a scheduled campaign with a PATCH." } ] } } }, "404": { "description": "\"\": \"not found\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "not found" } ] } } } }, "security": [ { "Authorization": [] } ] }, "patch": { "operationId": "PATCH_campaigns-campaign_id-schedules", "summary": "Update a Scheduled Campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows to you change the scheduled time and date for a campaign to be sent.**", "parameters": [ { "name": "body", "in": "body", "schema": { "title": "Update a Scheduled Campaign request", "type": "object", "properties": { "send_at": { "type": "integer", "format": "int64" } }, "required": [ "send_at" ], "example": { "send_at": 1489451436 } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "title": "Update a Scheduled Campaign response", "type": "object", "properties": { "id": { "type": "integer", "description": "The campaign ID" }, "send_at": { "type": "integer", "description": "The unix timestamp to send the campaign." }, "status": { "type": "string", "description": "The status of the schedule." } }, "required": [ "id", "send_at", "status" ] } }, "400": { "description": "\"\": \"The JSON you have submitted cannot be parsed.\"\n\"send_at\": \"Please choose a future time for sending your campaign.\"\n\"\":\"You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": "send_at", "message": "Please choose a future time for sending your campaign." }, { "field": null, "message": "The JSON you have submitted cannot be parsed." }, { "field": null, "message": "You do not have enough credits to send this campaign. Upgrade your plan to send https://app.sendgrid.com/settings/billing" } ] } } }, "403": { "description": "\"send_at\": \"You cannot update the send_at value of non-scheduled campaign.\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": "send_at", "message": "You cannot update the send_at value of non-scheduled campaign." } ] } } }, "404": { "description": "\"\": \"not found\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "not found" } ] } } } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_campaigns-campaign_id-schedules", "summary": "View Scheduled Time of a Campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to retrieve the date and time that a campaign has been scheduled to be sent.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "title": "View Scheduled Time of a Campaign response", "type": "object", "properties": { "send_at": { "type": "integer", "format": "int64" } }, "required": [ "send_at" ] }, "examples": { "application/json": { "send_at": 1490778528 } } }, "404": { "description": "\"\": \"not found\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "not found" } ] } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_campaigns-campaign_id-schedules", "summary": "Unschedule a Scheduled Campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to unschedule a campaign that has already been scheduled to be sent.**\n\nA successful unschedule will return a 204.\nIf the specified campaign is in the process of being sent, the only option is to cancel (a different method).", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "204": { "description": "", "schema": { "type": "null" } }, "403": { "description": "\"\": \"This campaign is already In Progress.\"\n\"\": \"This campaign is already Sent.\"\n\"\": \"This campaign is already Paused.\"\n\"\": \"This campaign is already Canceled.\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "This campaign is already In Progress." }, { "field": null, "message": "This campaign is already Sent." }, { "field": null, "message": "This campaign is already Paused." }, { "field": null, "message": "This campaign is already Canceled." } ] } } }, "404": { "description": "\"\": \"not found\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "not found" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/campaigns/{campaign_id}/schedules/test": { "parameters": [ { "name": "campaign_id", "in": "path", "required": true, "type": "integer" } ], "post": { "operationId": "POST_campaigns-campaign_id-schedules-test", "summary": "Send a Test Campaign", "tags": [ "Campaigns API" ], "description": "**This endpoint allows you to send a test campaign.**\n\nTo send to multiple addresses, use an array for the JSON \"to\" value [\"one@address\",\"two@address\"]", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "to": { "type": "string", "description": "The email address that should receive the test campaign.", "format": "email" } }, "required": [ "to" ], "example": { "to": "your.email@example.com" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "204": { "description": "", "schema": { "title": "Send a Test Campaign request", "type": "object", "properties": { "to": { "type": "string" } }, "required": [ "to" ] } }, "400": { "description": "\"\": \"The JSON you have submitted cannot be parsed.\"\n\"to\": \"Please provide an email address to which the test should be sent.\"\n\"to\": \"You can only send tests to 10 addresses at a time.\"\n\"subject\": \"Please add a subject to your campaign before sending a test.\"\n\"plain_content\": \"Plain content and html content can't both be blank. Please set one of these values before sending a test.\"\n\"sender_id\": \"Please assign a sender identity to your campaign before sending a test.\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": "send_at", "message": "Please choose a future time for sending your campaign." }, { "field": null, "message": "The JSON you have submitted cannot be parsed." }, { "field": null, "message": "You do not have enough credits to send this campaign. Upgrade your plan to send more: https://app.sendgrid.com/settings/billing" } ] } } }, "404": { "description": "\"\": \"not found\"", "schema": { "$ref": "#/definitions/global_error_response_schema" }, "examples": { "application/json": { "errors": [ { "field": null, "message": "not found" } ] } } } }, "security": [ { "Authorization": [] } ] } }, "/templates": { "post": { "operationId": "POST_templates", "summary": "Create a transactional template.", "tags": [ "Transactional Templates" ], "description": "**This endpoint allows you to create a transactional template.**", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name for the new transactional template.", "maxLength": 100 }, "generation": { "type": "string", "description": "Defines whether the template supports dynamic replacement.", "enum": [ "legacy", "dynamic" ], "default": "legacy" } }, "required": [ "name" ], "example": { "name": "example_name", "generation": "dynamic" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "201": { "description": "", "schema": { "$ref": "#/definitions/transactional_template" }, "examples": { "application/json": { "id": "733ba07f-ead1-41fc-933a-3976baa23716", "name": "example_name", "generation": "legacy", "versions": [] } } } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_templates", "summary": "Retrieve paged transactional templates.", "tags": [ "Transactional Templates" ], "description": "**This endpoint allows you to retrieve all transactional templates.**", "parameters": [ { "name": "generations", "in": "query", "description": "Comma-delimited list specifying which generations of templates to return. Options are `legacy`, `dynamic` or `legacy,dynamic`.", "required": false, "type": "string", "default": "legacy", "enum": [ "legacy", "dynamic", "legacy,dynamic" ] }, { "name": "page_size", "in": "query", "description": "The number of templates to be returned in each page of results", "required": true, "type": "number", "minimum": 1, "maximum": 200 }, { "name": "page_token", "in": "query", "description": "A token corresponding to a specific page of results, as provided by metadata", "required": false, "type": "string" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "object", "properties": { "result": { "type": "array", "description": "", "items": { "$ref": "#/definitions/transactional-templates-template-lean" } }, "_metadata": { "$ref": "#/definitions/_metadata" } } }, "examples": { "application/json": { "result": [ { "id": "fae7c985-eb92-4b47-9987-28ec29dbc698", "name": "example_name", "generation": "legacy", "updated_at ": "2020-11-12 12:00:09", "versions": [] } ], "_metadata": { "self": "https://api.sendgrid.com/v3/templates", "count": 1 } } } }, "400": { "description": "", "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "": { "type": "string" }, "message": { "type": "string" }, "error_id": { "type": "string" } } } } } } } }, "security": [ { "Authorization": [] } ] } }, "/templates/{template_id}": { "parameters": [ { "name": "template_id", "in": "path", "required": true, "type": "string" } ], "post": { "operationId": "POST_templates-template_id", "summary": "Duplicate a transactional template.", "tags": [ "Transactional Templates" ], "description": "**This endpoint allows you to duplicate a transactional template.**", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name for the new transactional template.", "maxLength": 100 } }, "example": { "name": "example_name" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "201": { "description": "", "schema": { "$ref": "#/definitions/transactional_template" }, "examples": { "application/json": { "id": "733ba07f-ead1-41fc-933a-3976baa2371", "name": "example_name", "generation": "dynamic", "updated_at ": "2019-03-13T11:52:41.009Z", "versions": [] } } } }, "security": [ { "Authorization": [] } ] }, "get": { "operationId": "GET_templates-template_id", "summary": "Retrieve a single transactional template.", "tags": [ "Transactional Templates" ], "description": "**This endpoint allows you to retrieve a single transactional template.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/transactional_template" }, "examples": { "application/json": { "id": "40da60e6-66f3-4223-9406-ba58b7f55a62", "name": "Duis in dolor", "generation": "legacy", "updated_at ": "2020-12-12 58:26:65", "versions": [] } } } }, "security": [ { "Authorization": [] } ] }, "patch": { "operationId": "PATCH_templates-template_id", "summary": "Edit a transactional template.", "tags": [ "Transactional Templates" ], "description": "**This endpoint allows you to edit the name of a transactional template.**\n\nTo edit the template itself, [create a new transactional template version](https://sendgrid.api-docs.io/v3.0/transactional-templates-versions/create-a-new-transactional-template-version).", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the transactional template.", "maxLength": 100 } }, "example": { "name": "new_example_name" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/transactional_template" }, "examples": { "application/json": { "id": "733ba07f-ead1-41fc-933a-3976baa23716", "name": "new_example_name", "versions": [] } } } }, "security": [ { "Authorization": [] } ] }, "delete": { "operationId": "DELETE_templates-template_id", "summary": "Delete a template.", "tags": [ "Transactional Templates" ], "description": "**This endpoint allows you to delete a transactional template.**", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "204": { "description": "", "schema": { "type": "object" } } }, "security": [ { "Authorization": [] } ] } }, "/templates/{template_id}/versions": { "parameters": [ { "name": "template_id", "in": "path", "required": true, "type": "string", "format": "uuid" } ], "post": { "operationId": "POST_templates-template_id-versions", "summary": "Create a new transactional template version.", "tags": [ "Transactional Templates Versions" ], "description": "**This endpoint allows you to create a new version of a template.**", "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/transactional_template_version_create", "example": { "active": 1, "name": "example_version_name", "html_content": "", "plain_content": "Plain text content", "generate_plain_content": false, "subject": "Something something unsubscribe <% %> something something
\n", "landing": "subscribehere
\n", "plain_content": "Something something unsubscribe <% %> something something", "replace": "thetag", "url": "" } } } }, "security": [ { "Authorization": [] } ] }, "patch": { "operationId": "PATCH_tracking_settings-subscription", "summary": "Update Subscription Tracking Settings", "tags": [ "Settings - Tracking" ], "description": "**This endpoint allows you to update your current settings for subscription tracking.**\n\nSubscription tracking adds links to the bottom of your emails that allows your recipients to subscribe to, or unsubscribe from, your emails.", "parameters": [ { "name": "body", "in": "body", "schema": { "$ref": "#/definitions/subscription_tracking_settings", "example": { "enabled": true, "landing": "landing page html", "url": "url", "replace": "replacement tag", "html_content": "html content", "plain_content": "text content" } } }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "$ref": "#/definitions/subscription_tracking_settings" }, "examples": { "application/json": { "enabled": true, "landing": "landing page html", "url": "url", "replace": "replacement tag", "html_content": "html content", "plain_content": "text content" } } } }, "security": [ { "Authorization": [] } ] } }, "/stats": { "get": { "operationId": "GET_stats", "summary": "Retrieve global email statistics", "tags": [ "Stats" ], "description": "**This endpoint allows you to retrieve all of your global email statistics between a given date range.**\n\nParent accounts will see aggregated stats for their account and all subuser accounts. Subuser accounts will only see their own stats.", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:limit" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:offset" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:aggregated_by" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:start_date" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:end_date" } ], "responses": { "200": { "description": "", "schema": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "The date the stats were gathered." }, "stats": { "type": "array", "description": "The individual email activity stats.", "items": { "type": "object", "properties": { "metrics": { "$ref": "#/definitions/stats-advanced-global-stats" } } } } }, "required": [ "date", "stats" ] } }, "examples": { "application/json": [ { "date": "2015-11-03", "stats": [ { "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-11-04", "stats": [ { "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-11-05", "stats": [ { "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-11-06", "stats": [ { "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-11-07", "stats": [ { "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-11-08", "stats": [ { "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-11-09", "stats": [ { "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": [] } ] } }, "/geo/stats": { "get": { "operationId": "GET_geo-stats", "summary": "Retrieve email statistics by country and state/province.", "tags": [ "Stats" ], "description": "**This endpoint allows you to retrieve your email statistics segmented by country and state/province.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [User Guide](https://sendgrid.com/docs/User_Guide/Statistics/index.html).", "parameters": [ { "name": "country", "in": "query", "description": "The country you would like to see statistics for. Currently only supported for US and CA.", "type": "string", "enum": [ "US", "CA" ] }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:limit" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:offset" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:aggregated_by" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:start_date" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:end_date" } ], "responses": { "200": { "description": "", "schema": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "The date that the statistics were gathered." }, "stats": { "type": "array", "description": "The list of statistics.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of segmentation." }, "name": { "type": "string", "description": "The name of the specific segmentation." }, "metrics": { "$ref": "#/definitions/advanced_stats_clicks_opens" } } } } } } }, "examples": { "application/json": [ { "date": "2015-10-11", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-12", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-13", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-14", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-15", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-16", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-17", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-18", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-19", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-20", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-21", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 1, "unique_clicks": 0, "unique_opens": 1 } } ] }, { "date": "2015-10-22", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-23", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-24", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-25", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-26", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-27", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-28", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-29", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-30", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-31", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-01", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-02", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-03", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-04", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-05", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-06", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-07", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-08", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-09", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-10", "stats": [ { "type": "province", "name": "TX", "metrics": { "clicks": 0, "opens": 0, "unique_clicks": 0, "unique_opens": 0 } } ] } ] } } }, "security": [ { "Authorization": [] } ] } }, "/devices/stats": { "get": { "operationId": "GET_devices-stats", "summary": "Retrieve email statistics by device type.", "tags": [ "Stats" ], "description": "**This endpoint allows you to retrieve your email statistics segmented by the device type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\n## Available Device Types\n| **Device** | **Description** | **Example** |\n|---|---|---|\n| Desktop | Email software on desktop computer. | I.E., Outlook, Sparrow, or Apple Mail. |\n| Webmail |\tA web-based email client. | I.E., Yahoo, Google, AOL, or Outlook.com. |\n| Phone | A smart phone. | iPhone, Android, Blackberry, etc.\n| Tablet | A tablet computer. | iPad, android based tablet, etc. |\n| Other | An unrecognized device. |\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:limit" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:offset" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:aggregated_by" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:start_date" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:end_date" } ], "responses": { "200": { "description": "", "schema": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "The date that the statistics were gathered." }, "stats": { "type": "array", "description": "The list of statistics.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of segmentation." }, "name": { "type": "string", "description": "The name of the specific segmentation." }, "metrics": { "$ref": "#/definitions/advanced_stats_opens" } } } } } } }, "examples": { "application/json": [ { "date": "2015-10-11", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-12", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-13", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-14", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-15", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-16", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-17", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-18", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-19", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-20", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-21", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 1, "unique_opens": 1 } } ] }, { "date": "2015-10-22", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-23", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-24", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-25", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-26", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 2, "unique_opens": 2 } } ] }, { "date": "2015-10-27", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-28", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-29", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-30", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-31", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-01", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-02", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-03", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-04", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-05", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-06", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-07", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-08", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-09", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-10", "stats": [ { "type": "device", "name": "Webmail", "metrics": { "opens": 0, "unique_opens": 0 } } ] } ] } } }, "security": [ { "Authorization": [] } ] } }, "/clients/stats": { "get": { "operationId": "GET_clients-stats", "summary": "Retrieve email statistics by client type.", "tags": [ "Stats" ], "description": "**This endpoint allows you to retrieve your email statistics segmented by client type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" }, { "$ref": "#/parameters/trait:statsAdvancedStatsBaseQueryStrings:start_date" }, { "$ref": "#/parameters/trait:statsAdvancedStatsBaseQueryStrings:end_date" }, { "$ref": "#/parameters/trait:statsAdvancedStatsBaseQueryStrings:aggregated_by" } ], "responses": { "200": { "description": "", "schema": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "The date that the statistics were gathered." }, "stats": { "type": "array", "description": "The list of statistics.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of segmentation." }, "name": { "type": "string", "description": "The name of the specific segmentation." }, "metrics": { "$ref": "#/definitions/advanced_stats_opens" } } } } } } }, "examples": { "application/json": [ { "date": "2014-10-01", "stats": [ { "metrics": { "opens": 1, "unique_opens": 1 }, "name": "Gmail", "type": "client" } ] }, { "date": "2014-10-02", "stats": [ { "metrics": { "opens": 0, "unique_opens": 0 }, "name": "Gmail", "type": "client" } ] } ] } } }, "security": [ { "Authorization": [] } ] } }, "/clients/{client_type}/stats": { "parameters": [ { "name": "client_type", "in": "path", "description": "Specifies the type of client to retrieve stats for. Must be either \"phone\", \"tablet\", \"webmail\", or \"desktop\".", "required": true, "type": "string", "enum": [ "phone", "tablet", "webmail", "desktop" ] } ], "get": { "operationId": "GET_clients-client_type-stats", "summary": "Retrieve stats by a specific client type.", "tags": [ "Stats" ], "description": "**This endpoint allows you to retrieve your email statistics segmented by a specific client type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\n## Available Client Types\n- phone\n- tablet\n- webmail\n- desktop\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).", "parameters": [ { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" }, { "$ref": "#/parameters/trait:statsAdvancedStatsBaseQueryStrings:start_date" }, { "$ref": "#/parameters/trait:statsAdvancedStatsBaseQueryStrings:end_date" }, { "$ref": "#/parameters/trait:statsAdvancedStatsBaseQueryStrings:aggregated_by" } ], "responses": { "200": { "description": "", "schema": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "The date that the statistics were gathered." }, "stats": { "type": "array", "description": "The list of statistics.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of segmentation." }, "name": { "type": "string", "description": "The name of the specific segmentation." }, "metrics": { "$ref": "#/definitions/advanced_stats_opens" } } } } } } }, "examples": { "application/json": [ { "date": "2014-10-01", "stats": [ { "metrics": { "opens": 1, "unique_opens": 1 }, "name": "Gmail", "type": "client" } ] }, { "date": "2014-10-02", "stats": [ { "metrics": { "opens": 0, "unique_opens": 0 }, "name": "Gmail", "type": "client" } ] } ] } } }, "security": [ { "Authorization": [] } ] } }, "/mailbox_providers/stats": { "get": { "operationId": "GET_mailbox_providers-stats", "summary": "Retrieve email statistics by mailbox provider.", "tags": [ "Stats" ], "description": "**This endpoint allows you to retrieve your email statistics segmented by recipient mailbox provider.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).", "parameters": [ { "name": "mailbox_providers", "in": "query", "description": "The mail box providers to get statistics for. You can include up to 10 by including this parameter multiple times.", "type": "string" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:limit" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:offset" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:aggregated_by" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:start_date" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:end_date" } ], "responses": { "200": { "description": "", "schema": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "The date that the statistics were gathered." }, "stats": { "type": "array", "description": "The list of statistics.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of segmentation." }, "name": { "type": "string", "description": "The name of the specific segmentation." }, "metrics": { "$ref": "#/definitions/advanced_stats_mailbox_provider" } } } } } } }, "examples": { "application/json": [ { "date": "2015-10-11", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-12", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-13", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-14", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-15", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-16", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-17", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-18", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-19", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-20", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-21", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 1, "drops": 0, "opens": 1, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 1 } } ] }, { "date": "2015-10-22", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-23", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-24", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-25", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-26", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 2, "drops": 0, "opens": 2, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 2 } } ] }, { "date": "2015-10-27", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-28", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-29", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-30", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-10-31", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-01", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-02", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-03", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-04", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-05", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-06", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-07", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-08", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-09", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] }, { "date": "2015-11-10", "stats": [ { "type": "mailbox_provider", "name": "Gmail", "metrics": { "blocks": 0, "bounces": 0, "clicks": 0, "deferred": 0, "delivered": 0, "drops": 0, "opens": 0, "processed": 0, "requests": 0, "spam_reports": 0, "unique_clicks": 0, "unique_opens": 0 } } ] } ] } } }, "security": [ { "Authorization": [] } ] } }, "/browsers/stats": { "get": { "operationId": "GET_browsers-stats", "summary": "Retrieve email statistics by browser.", "tags": [ "Stats" ], "description": "**This endpoint allows you to retrieve your email statistics segmented by browser type.**\n\n**We only store up to 7 days of email activity in our database.** By default, 500 items will be returned per request via the Advanced Stats API endpoints.\n\nAdvanced Stats provide a more in-depth view of your email statistics and the actions taken by your recipients. You can segment these statistics by geographic location, device type, client type, browser, and mailbox provider. For more information about statistics, please see our [Statistics Overview](https://sendgrid.com/docs/ui/analytics-and-reporting/stats-overview/).", "parameters": [ { "name": "browsers", "in": "query", "description": "The browsers to get statistics for. You can include up to 10 different browsers by including this parameter multiple times.", "type": "string" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:limit" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:offset" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:aggregated_by" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:start_date" }, { "$ref": "#/parameters/trait:statsAdvancedQueryStringsLimitOffset:end_date" } ], "responses": { "200": { "description": "", "schema": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "description": "The date that the statistics were gathered." }, "stats": { "type": "array", "description": "The list of statistics.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "The type of segmentation." }, "name": { "type": "string", "description": "The name of the specific segmentation." }, "metrics": { "$ref": "#/definitions/advanced_stats_clicks" } } } } } } }, "examples": { "application/json": [ { "date": "2014-10-01", "stats": [ { "metrics": { "clicks": 0, "unique_clicks": 0 }, "name": "Chrome", "type": "browser" }, { "metrics": { "clicks": 1, "unique_clicks": 1 }, "name": "Firefox", "type": "browser" } ] }, { "date": "2014-10-02", "stats": [ { "metrics": { "clicks": 0, "unique_clicks": 0 }, "name": "Chrome", "type": "browser" }, { "metrics": { "clicks": 1, "unique_clicks": 1 }, "name": "Firefox", "type": "browser" } ] } ] } } }, "security": [ { "Authorization": [] } ] } }, "/suppression/bounces": { "get": { "operationId": "GET_suppression-bounces", "summary": "Retrieve all bounces", "tags": [ "Bounces API" ], "description": "**This endpoint allows you to retrieve all of your bounces.**", "parameters": [ { "name": "start_time", "in": "query", "description": "Refers start of the time range in unix timestamp when a bounce was created (inclusive).", "type": "integer" }, { "name": "end_time", "in": "query", "description": "Refers end of the time range in unix timestamp when a bounce was created (inclusive).", "type": "integer" }, { "name": "Accept", "in": "header", "required": true, "type": "string", "default": "application/json" }, { "$ref": "#/parameters/trait:onBehalfOfSubuser:on-behalf-of" } ], "responses": { "200": { "description": "", "schema": { "type": "array", "items": { "$ref": "#/definitions/bounce_response" } }, "examples": { "application/json": [ { "created": 1250337600, "email": "example@example.com", "reason": "550 5.1.1 The email account that you tried to reach does not exist. Please try double-checking the recipient's email address for typos or unnecessary spaces. Learn more at https://support.google.com/mail/answer/6596 o186si2389584ioe.63 - gsmtp ", "status": "5.1.1" }, { "created": 1250337600, "email": "example@example.com", "reason": "550 5.1.1<% body %>Example
\n" } }, "ip_warmup_response": { "title": "IP Warmup: IP", "type": "array", "items": { "type": "object", "properties": { "ip": { "type": "string", "description": "The IP address." }, "start_date": { "type": "integer", "description": "A Unix timestamp indicating when the IP address entered warmup mode." } }, "required": [ "ip", "start_date" ] }, "example": [ { "ip": "0.0.0.0", "start_date": 1409616000 } ] }, "monitor": { "title": "Create monitor settings request", "type": "object", "properties": { "email": { "type": "string", "description": "The email address to which Sendgrid should send emails for monitoring.", "format": "email" }, "frequency": { "type": "number", "description": "The frequency at which to forward monitoring emails. An email will be sent when your subuser sends this many (e.g., 1,000) emails." } }, "required": [ "email", "frequency" ], "example": { "email": "example@example.com", "frequency": 50000 } }, "global_error_response_schema": { "title": "Global Error Response Schema", "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string", "description": "the error message" }, "field": { "type": [ "string", "null" ], "description": "the field that generated the error" }, "help": { "type": "object", "description": "helper text or docs for troubleshooting" } }, "required": [ "message" ] } }, "id": { "type": "string" } }, "example": { "errors": [ { "field": "field_name", "message": "error message" } ] } }, "advanced_stats_mailbox_provider": { "title": "Stats: Advanced Stats for Mailbox Provider", "description": "The individual events and their stats.", "allOf": [ { "$ref": "#/definitions/advanced_stats_clicks_opens" }, { "type": "object", "description": "The individual events and their stats.", "properties": { "blocks": { "type": "integer", "description": "The number of emails that were not allowed to be delivered by ISPs." }, "bounces": { "type": "integer", "description": "The number of emails that bounced instead of being delivered." }, "deferred": { "type": "integer", "description": "The number of emails that temporarily could not be delivered." }, "delivered": { "type": "integer", "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." }, "drops": { "type": "integer", "description": "The number of emails that were not delivered due to the recipient email address being on a suppression list." }, "requests": { "type": "integer", "description": "The number of emails that were requested to be delivered." }, "processed": { "type": "integer", "description": "Requests from your website, application, or mail client via SMTP Relay or the Web API that SendGrid processed." }, "spam_reports": { "type": "integer", "description": "The number of recipients who marked your email as spam." } } } ] }, "contactdb_custom_field_with_id": { "title": "ContactDB Custom field schema with ID.", "allOf": [ { "$ref": "#/definitions/contactdb_custom_field" }, { "type": "object", "properties": { "id": { "type": "number", "description": "The ID of the custom field." } } } ] }, "ip_pool": { "title": "IP Pools: Pool", "type": "object", "properties": { "name": { "type": "string", "description": "The name of the IP pool.", "maxLength": 64 } }, "required": [ "name" ] }, "google_analytics_settings": { "title": "Settings: Google Analytics", "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Indicates if Google Analytics is enabled." }, "utm_campaign": { "type": "string", "description": "The name of the campaign." }, "utm_content": { "type": "string", "description": "Used to differentiate ads" }, "utm_medium": { "type": "string", "description": "Name of the marketing medium (e.g. \"Email\")." }, "utm_source": { "type": "string", "description": "Name of the referrer source. " }, "utm_term": { "type": "string", "description": "Any paid keywords." } }, "example": { "enabled": true, "utm_source": "sendgrid.com", "utm_medium": "email", "utm_term": "", "utm_content": "", "utm_campaign": "website" } }, "event-webhook-response": { "title": "Webhooks: Event Webhook Response", "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Indicates if the event webhook is enabled." }, "url": { "type": "string", "description": "The URL that you want the event webhook to POST to." }, "group_resubscribe": { "type": "boolean", "description": "Recipient resubscribes to specific group by updating preferences. You need to enable Subscription Tracking for getting this type of event." }, "delivered": { "type": "boolean", "description": "Message has been successfully delivered to the receiving server." }, "group_unsubscribe": { "type": "boolean", "description": "Recipient unsubscribe from specific group, by either direct link or updating preferences. You need to enable Subscription Tracking for getting this type of event." }, "spam_report": { "type": "boolean", "description": "Recipient marked a message as spam." }, "bounce": { "type": "boolean", "description": "Receiving server could not or would not accept message." }, "deferred": { "type": "boolean", "description": "Recipient's email server temporarily rejected message." }, "unsubscribe": { "type": "boolean", "description": "Recipient clicked on message's subscription management link. You need to enable Subscription Tracking for getting this type of event." }, "processed": { "type": "boolean", "description": "Message has been received and is ready to be delivered." }, "open": { "type": "boolean", "description": "Recipient has opened the HTML message. You need to enable Open Tracking for getting this type of event." }, "click": { "type": "boolean", "description": "Recipient clicked on a link within the message. You need to enable Click Tracking for getting this type of event." }, "dropped": { "type": "boolean", "description": "You may see the following drop reasons: Invalid SMTPAPI header, Spam Content (if spam checker app enabled), Unsubscribed Address, Bounced Address, Spam Reporting Address, Invalid, Recipient List over Package Quota" }, "oauth_client_id": { "type": "string", "description": "The client ID Twilio SendGrid sends to your OAuth server or service provider to generate an OAuth access token." }, "oauth_token_url": { "type": "string", "description": "The URL where Twilio SendGrid sends the Client ID and Client Secret to generate an access token. This should be your OAuth server or service provider." } }, "required": [ "enabled", "url", "group_resubscribe", "delivered", "group_unsubscribe", "spam_report", "bounce", "deferred", "unsubscribe", "processed", "open", "click", "dropped" ] }, "user_profile": { "title": "User: Profile", "type": "object", "properties": { "address": { "type": "string", "description": "The street address for this user profile." }, "address2": { "type": "string", "description": "An optional second line for the street address of this user profile." }, "city": { "type": "string", "description": "The city for the user profile." }, "company": { "type": "string", "description": "That company that this user profile is associated with." }, "country": { "type": "string", "description": "Th country of this user profile." }, "first_name": { "type": "string", "description": "The first name of the user." }, "last_name": { "type": "string", "description": "The last name of the user." }, "phone": { "type": "string", "description": "The phone number for the user." }, "state": { "type": "string", "description": "The state for this user." }, "website": { "type": "string", "description": "The website associated with this user." }, "zip": { "type": "string", "description": "The zip code for this user." } }, "example": { "address": "1451 Larimer Street, 3rd floor", "address2": "", "city": "Denver, CO", "company": "SendGrid", "country": "US", "first_name": "Matthew", "last_name": "Bernier", "phone": "7208788003", "state": "CO", "website": "http://sendgrid.com", "zip": "80202" } }, "mail_settings_footer": { "title": "Mail Settings: Footer", "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Indicates if the Footer mail setting is currently enabled." }, "html_content": { "type": "string", "description": "The custom HTML content of your email footer." }, "plain_content": { "type": "string", "description": "The plain text content of your email footer." } }, "example": { "enabled": true, "html_content": "Example HTML content", "plain_content": "Example plain content" } }, "category_stats": { "title": "Stats: Category Stats", "type": "object", "properties": { "date": { "type": "string", "description": "The date the statistics were gathered." }, "stats": { "type": "array", "items": { "type": "object", "properties": { "metrics": { "type": "object", "properties": { "blocks": { "type": "integer", "description": "The number of emails that were not allowed to be delivered by ISPs." }, "bounce_drops": { "type": "integer", "description": "The number of emails that were dropped because of a bounce." }, "bounces": { "type": "integer", "description": "The number of emails that bounced instead of being delivered." }, "clicks": { "type": "integer", "description": "The number of links that were clicked." }, "deferred": { "type": "integer", "description": "The number of emails that temporarily could not be delivered." }, "delivered": { "type": "integer", "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." }, "invalid_emails": { "type": "integer", "description": "The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid." }, "opens": { "type": "integer", "description": "The total number of times your emails were opened by recipients." }, "processed": { "type": "integer", "description": "Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed." }, "requests": { "type": "integer", "description": "The number of emails that were requested to be delivered." }, "spam_report_drops": { "type": "integer", "description": "The number of emails that were dropped due to a recipient previously marking your emails as spam." }, "spam_reports": { "type": "integer", "description": "The number of recipients who marked your email as spam." }, "unique_clicks": { "type": "integer", "description": "The number of unique recipients who clicked links in your emails." }, "unique_opens": { "type": "integer", "description": "The number of unique recipients who opened your emails." }, "unsubscribe_drops": { "type": "integer", "description": "The number of emails dropped due to a recipient unsubscribing from your emails." }, "unsubscribes": { "type": "integer", "description": "The number of recipients who unsubscribed from your emails." } }, "required": [ "blocks", "bounce_drops", "bounces", "clicks", "deferred", "delivered", "invalid_emails", "opens", "processed", "requests", "spam_report_drops", "spam_reports", "unique_clicks", "unique_opens", "unsubscribe_drops", "unsubscribes" ] }, "name": { "type": "string", "description": "The name of the category." }, "type": { "type": "string", "description": "How you are segmenting your statistics." } }, "required": [ "type" ] } } }, "required": [ "date" ], "example": { "date": "2015-01-01", "stats": [ { "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 }, "name": "cat1", "type": "category" }, { "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 }, "name": "cat2", "type": "category" } ] } }, "parse-setting": { "title": "Parse Setting", "type": "object", "properties": { "url": { "type": "string", "description": "The public URL where you would like SendGrid to POST the data parsed from your email. Any emails sent with the given hostname provided (whose MX records have been updated to point to SendGrid) will be parsed and POSTed to this URL." }, "hostname": { "type": "string", "description": "A specific and unique domain or subdomain that you have created to use exclusively to parse your incoming email. For example, `parse.yourdomain.com`." }, "spam_check": { "type": "boolean", "description": "Indicates if you would like SendGrid to check the content parsed from your emails for spam before POSTing them to your domain." }, "send_raw": { "type": "boolean", "description": "Indicates if you would like SendGrid to post the original MIME-type content of your parsed email. When this parameter is set to `true`, SendGrid will send a JSON payload of the content of your email." } }, "example": { "url": "http://email.myhostname.com", "hostname": "myhostname.com", "spam_check": false, "send_raw": true } }, "transactional_template": { "title": "Transactional Templates: Template", "allOf": [ { "$ref": "#/definitions/transactional-templates-template-lean" }, { "type": "object", "properties": { "warning": { "$ref": "#/definitions/transactional-template-warning" } } } ], "example": { "id": "33feeff2-5069-43fe-8853-428651e5be79", "name": "example_name", "updated_at ": "2021-04-28 13:12:46", "warning": { "message": "Sample warning message" }, "generation": "legacy" } }, "contactdb_list": { "title": "ContactDB lists", "type": "object", "properties": { "id": { "type": "integer", "description": "The reference ID of your list." }, "name": { "type": "string", "description": "The name of your list. Must be unique against all other list and segment names." }, "recipient_count": { "type": "integer", "description": "The count of recipients currently in the list." } }, "required": [ "id", "name", "recipient_count" ], "example": { "id": 1, "name": "listname", "recipient_count": 0 } }, "suppression_group": { "title": "Suppressions: Suppression Group", "type": "object", "properties": { "id": { "type": "number", "description": "The id of the suppression group." }, "name": { "type": "string", "description": "The name of the suppression group. Each group created by a user must have a unique name.", "maxLength": 30 }, "description": { "type": "string", "description": "A description of the suppression group.", "maxLength": 100 }, "last_email_sent_at": { "type": "null" }, "is_default": { "type": "boolean", "default": false, "description": "Indicates if this is the default suppression group." }, "unsubscribes": { "type": "integer", "description": "The unsubscribes associated with this group." } }, "required": [ "id", "name", "description" ] }, "mail_settings_bounce_purge": { "title": "Mail Settings: Bounce Purge", "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Indicates if the bounce purge mail setting is enabled." }, "soft_bounces": { "type": [ "integer", "null" ], "description": "The number of days after which SendGrid will purge all contacts from your soft bounces suppression lists." }, "hard_bounces": { "type": [ "integer", "null" ], "description": "The number of days after which SendGrid will purge all contacts from your hard bounces suppression lists." } }, "example": { "enabled": false, "soft_bounces": 1234, "hard_bounces": null } }, "transactional_template_version_output": { "title": "Transactional Templates: Version Output", "allOf": [ { "type": "object", "properties": { "warnings": { "type": "array", "items": { "$ref": "#/definitions/transactional-template-warning" } } } }, { "$ref": "#/definitions/transactional_template_version_create" }, { "$ref": "#/definitions/transactional-templates-version-output-lean" } ] }, "credentials": { "title": "Credentials", "type": "object", "properties": { "permissions": { "type": "object", "properties": { "api": { "type": "string" }, "mail": { "type": "string" }, "web": { "type": "string" } } }, "username": { "type": "string" } }, "example": { "address": "1234 example street", "address2": null, "city": "Denver", "company": "Company name", "country": "US", "email": "example@example.com", "first_name": "Example", "last_name": "User", "phone": "(555) 555-5555", "state": "CO", "zip": "55555" } }, "global:id": { "title": "Global: ID", "type": "integer" }, "mail_settings_forward_spam": { "title": "Mail Settings: Forward Spam", "type": "object", "properties": { "email": { "type": "string", "description": "The email address where you would like the spam reports to be forwarded." }, "enabled": { "type": "boolean", "description": "Indicates if the Forward Spam setting is enabled." } }, "example": { "email": "", "enabled": true } }, "campaign_request": { "title": "Campaigns Request", "type": "object", "properties": { "title": { "type": "string", "description": "The display title of your campaign. This will be viewable by you in the Marketing Campaigns UI." }, "subject": { "type": [ "string", "null" ], "description": "The subject of your campaign that your recipients will see." }, "sender_id": { "type": [ "null", "integer" ], "description": "The ID of the \"sender\" identity that you have created. Your recipients will see this as the \"from\" on your marketing emails." }, "list_ids": { "type": [ "array", "null" ], "description": "The IDs of the lists you are sending this campaign to. You can have both segment IDs and list IDs", "items": { "type": "integer" } }, "segment_ids": { "type": [ "array", "null" ], "description": "The segment IDs that you are sending this list to. You can have both segment IDs and list IDs. Segments are limited to 10 segment IDs.", "items": { "type": "integer" } }, "categories": { "type": [ "array", "null" ], "description": "The categories you would like associated to this campaign.", "items": { "type": "string" } }, "suppression_group_id": { "type": [ "null", "integer" ], "description": "The suppression group that this marketing email belongs to, allowing recipients to opt-out of emails of this type." }, "custom_unsubscribe_url": { "type": [ "string", "null" ], "description": "This is the url of the custom unsubscribe page that you provide for customers to unsubscribe from your suppression groups." }, "ip_pool": { "type": [ "string", "null" ], "description": "The pool of IPs that you would like to send this email from." }, "html_content": { "type": [ "string", "null" ], "description": "The HTML of your marketing email." }, "plain_content": { "type": [ "string", "null" ], "description": "The plain text content of your emails." }, "editor": { "type": "string", "enum": [ "code", "design" ], "description": "The editor used in the UI." } }, "required": [ "title" ], "example": { "id": 986724, "title": "May Newsletter", "subject": "New Products for Summer!", "sender_id": 124451, "list_ids": [ 110, 124 ], "segment_ids": [ 110 ], "categories": [ "summer line" ], "suppression_group_id": 42, "custom_unsubscribe_url": "", "ip_pool": "marketing", "html_content": "Check out our summer line!
", "plain_content": "Check out our summer line!", "status": "Draft" } }, "subuser_stats": { "title": "subuser_stats", "type": "object", "properties": { "date": { "type": "string", "description": "The date the statistics were gathered." }, "stats": { "type": "array", "description": "The list of statistics.", "items": { "type": "object", "properties": { "first_name": { "type": "string", "description": "The first name of the subuser." }, "last_name": { "type": "string", "description": "The last name of the subuser." }, "metrics": { "type": "object", "properties": { "blocks": { "type": "integer", "description": "The number of emails that were not allowed to be delivered by ISPs." }, "bounce_drops": { "type": "integer", "description": "The number of emails that were dropped because of a bounce." }, "bounces": { "type": "integer", "description": "The number of emails that bounced instead of being delivered." }, "clicks": { "type": "integer", "description": "The number of links that were clicked in your emails." }, "deferred": { "type": "integer", "description": "The number of emails that temporarily could not be delivered." }, "delivered": { "type": "integer", "description": "The number of emails SendGrid was able to confirm were actually delivered to a recipient." }, "invalid_emails": { "type": "integer", "description": "The number of recipients who had malformed email addresses or whose mail provider reported the address as invalid." }, "opens": { "type": "integer", "description": "The total number of times your emails were opened by recipients." }, "processed": { "type": "integer", "description": "Requests from your website, application, or mail client via SMTP Relay or the API that SendGrid processed." }, "requests": { "type": "integer", "description": "The number of emails that were requested to be delivered." }, "spam_report_drops": { "type": "integer", "description": "The number of emails that were dropped due to a recipient previously marking your emails as spam." }, "spam_reports": { "type": "integer", "description": "The number of recipients who marked your email as spam." }, "unique_clicks": { "type": "integer", "description": "The number of unique recipients who clicked links in your emails." }, "unique_opens": { "type": "integer", "description": "The number of unique recipients who opened your emails." }, "unsubscribe_drops": { "type": "integer", "description": "The number of emails dropped due to a recipient unsubscribing from your emails." }, "unsubscribes": { "type": "integer", "description": "The number of recipients who unsubscribed from your emails." } } }, "name": { "type": "string", "description": "The username of the subuser." }, "type": { "type": "string", "description": "The type of account." } } } } }, "example": { "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" } ] } }, "user_scheduled_send_status": { "title": "User Scheduled Send status", "allOf": [ { "$ref": "#/definitions/mail_batch_id" }, { "type": "object", "description": "The status of the scheduled send.", "properties": { "status": { "type": "string", "description": "The status of the scheduled send.", "enum": [ "cancel", "pause" ] } }, "required": [ "status" ] } ], "example": { "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi", "status": "pause" } }, "advanced_stats_clicks_opens": { "title": "Stats: Advanced Stats with Clicks and Opens", "description": "The individual events and their stats.", "allOf": [ { "$ref": "#/definitions/advanced_stats_clicks" }, { "$ref": "#/definitions/advanced_stats_opens" } ] }, "contactdb_segments_with_id": { "title": "ContactDB:: Segments with ID", "allOf": [ { "type": "object", "properties": { "id": { "type": "number", "description": "The ID of the segment." } }, "required": [ "id" ] }, { "$ref": "#/definitions/contactdb_segments" } ] }, "advanced_stats_clicks": { "title": "Stats: Advanced Stats with Clicks", "type": "object", "description": "The individual events and their stats.", "properties": { "clicks": { "type": "integer", "description": "The number of links that were clicked in your emails." }, "unique_clicks": { "type": "integer", "description": "The number of unique recipients who clicked links in your emails." } } }, "contactdb_recipient": { "title": "ContactDB: Recipient", "type": "object", "properties": { "recipients": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "The ID of this recipient." }, "created_at": { "type": "number", "description": "The time this record was created in your contactdb, in unixtime." }, "custom_fields": { "type": "array", "description": "The custom fields assigned to this recipient and their values.", "items": { "$ref": "#/definitions/contactdb_custom_field_with_id_value" } }, "email": { "type": "string", "description": "The email address of this recipient. This is a default custom field that SendGrid provides.", "format": "email" }, "first_name": { "type": [ "string", "null" ], "description": "The first name of this recipient. This is a default custom field that SendGrid provides." }, "last_name": { "type": [ "string", "null" ], "description": "The last name of the recipient." }, "last_clicked": { "type": [ "number", "null" ], "description": "The last time this recipient clicked a link from one of your campaigns, in unixtime." }, "last_emailed": { "type": [ "number", "null" ], "description": "The last time this user was emailed by one of your campaigns, in unixtime." }, "last_opened": { "type": [ "number", "null" ], "description": "The last time this recipient opened an email from you, in unixtime." }, "updated_at": { "type": "number", "description": "The last update date for this recipient's record." } }, "required": [ "email" ] } } } }, "mail_settings_patch": { "title": "Mail Settings: Patch", "type": "object", "properties": { "enabled": { "type": "boolean", "description": "Indicates if the mail setting is enabled." }, "email": { "type": "string", "description": "The email address of the recipient." } }, "example": { "enabled": true, "email": "email@example.com" } }, "mail_settings_forward_bounce": { "title": "Mail Settings: Forward Bounce", "type": "object", "properties": { "email": { "type": [ "string", "null" ], "description": "The email address that you would like your bounce reports forwarded to." }, "enabled": { "type": "boolean", "description": "Indicates if the bounce forwarding mail setting is enabled." } }, "example": { "enabled": false, "email": null } }, "mail_batch_id": { "title": "Mail Batch ID", "type": "object", "properties": { "batch_id": { "type": "string", "pattern": "^[a-zA-Z0-9\\-\\_]" } }, "required": [ "batch_id" ], "example": { "batch_id": "HkJ5yLYULb7Rj8GKSx7u025ouWVlMgAi" } }, "subuser_post": { "title": "Subuser::POST", "type": "object", "properties": { "username": { "type": "string", "description": "The username of the subuser." }, "user_id": { "type": "number", "description": "The user ID for this subuser." }, "email": { "type": "string", "description": "The email address for this subuser.", "format": "email" }, "signup_session_token": { "type": "string" }, "authorization_token": { "type": "string" }, "credit_allocation": { "type": "object", "properties": { "type": { "type": "string" } } } }, "required": [ "username", "user_id", "email" ], "example": { "username": "example_subuser", "user_id": 1234, "email": "example@example.com", "signup_session_token": "", "authorization_token": "", "credit_allocation": { "type": "unlimited" } } }, "contactdb_recipient_count": { "title": "ContactDB: Recipient Count", "type": "object", "properties": { "recipient_count": { "type": "number", "description": "The count of recipients." } }, "required": [ "recipient_count" ], "example": { "recipient_count": 1234 } }, "authentication::domain": { "title": "Domain Authentication - Mandatory Subdomain", "type": "object", "properties": { "id": { "type": "number", "description": "The ID of the authenticated domain." }, "user_id": { "type": "number", "description": "The ID of the user that this domain is associated with." }, "subdomain": { "type": "string", "description": "The subdomain to use for this authenticated domain." }, "domain": { "type": "string", "description": "The domain to be authenticated." }, "username": { "type": "string", "description": "The username that this domain will be associated with." }, "ips": { "type": "array", "description": "The IPs to be included in the custom SPF record for this authenticated domain.", "items": { "type": "string" } }, "custom_spf": { "type": "boolean", "description": "Indicates whether this authenticated domain uses custom SPF." }, "default": { "type": "boolean", "description": "Indicates if this is the default authenticated domain." }, "legacy": { "type": "boolean", "description": "Indicates if this authenticated domain was created using the legacy whitelabel tool. If it is a legacy whitelabel, it will still function, but you'll need to create a new authenticated domain if you need to update it." }, "automatic_security": { "type": "boolean", "description": "Indicates if this authenticated domain uses automated security." }, "valid": { "type": "boolean", "description": "Indicates if this is a valid authenticated domain." }, "dns": { "type": "object", "description": "The DNS records used to authenticate the sending domain.", "required": [ "mail_cname", "dkim1", "dkim2" ], "properties": { "mail_cname": { "type": "object", "description": "The CNAME for your sending domain that points to sendgrid.net.", "required": [ "valid", "type", "host", "data" ], "properties": { "valid": { "type": "boolean", "description": "Indicates if this is a valid CNAME." }, "type": { "type": "string", "description": "The type of DNS record." }, "host": { "type": "string", "description": "The domain that this CNAME is created for.", "format": "hostname" }, "data": { "type": "string", "description": "The CNAME record." } } }, "dkim1": { "type": "object", "description": "A DNS record.", "required": [ "valid", "type", "host", "data" ], "properties": { "valid": { "type": "boolean", "description": "Indicates if this is a valid DNS record." }, "type": { "type": "string", "description": "The type of DNS record." }, "host": { "type": "string", "description": "The domain that this DNS record was created for." }, "data": { "type": "string", "description": "The DNS record." } } }, "dkim2": { "type": "object", "description": "A DNS record.", "required": [ "valid", "type", "host", "data" ], "properties": { "valid": { "type": "boolean", "description": "Indicates if this is a valid DNS record." }, "type": { "type": "string", "description": "The type of DNS record." }, "host": { "type": "string", "description": "The domain that this DNS record was created for." }, "data": { "type": "string", "description": "The DNS record." } } } } } }, "required": [ "id", "user_id", "subdomain", "domain", "username", "ips", "custom_spf", "default", "legacy", "automatic_security", "valid", "dns" ], "example": { "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" } } } }, "contactdb_custom_field_with_id_value": { "title": "ContactDB Custom field schema.", "allOf": [ { "$ref": "#/definitions/contactdb_custom_field_with_id" }, { "type": "object", "properties": { "value": { "type": [ "string", "null" ], "description": "The value of this recipient's custom field" } } } ] }, "transactional_template_version_create": { "title": "Transactional Templates: Version Create", "type": "object", "properties": { "active": { "type": "integer", "description": "Set the version as the active version associated with the template (0 is inactive, 1 is active). Only one version of a template can be active. The first version created for a template will automatically be set to Active.", "enum": [ 0, 1 ] }, "name": { "type": "string", "description": "Name of the transactional template version.", "maxLength": 100 }, "html_content": { "type": "string", "description": "The HTML content of the version. Maximum of 1048576 bytes allowed.", "maxLength": 1048576 }, "plain_content": { "type": "string", "description": "Text/plain content of the transactional template version. Maximum of 1048576 bytes allowed.", "maxLength": 1048576, "default": "\n \n
\n
\n \n
| \n