{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "Single-send",
    "version" : "v4",
    "x-hubspot-product-tier-requirements" : {
      "marketing" : "ENTERPRISE",
      "sales" : "FREE",
      "service" : "FREE",
      "cms" : "FREE",
      "commerce" : "FREE",
      "crmHub" : "FREE",
      "dataHub" : "FREE"
    },
    "x-hubspot-api-use-case" : "Any marketing emails sent through the single-send API will automatically be associated with contact records based on their email address, and update non-marketing contacts and set them to marketing contacts . ",
    "x-hubspot-related-documentation" : [ {
      "name" : "Single Send API Guide ",
      "url" : "https://developers.hubspot.com/docs/guides/api/marketing/emails/single-send-api"
    } ],
    "x-hubspot-introduction" : "The single-send API allows you to send template emails created in the HubSpot marketing email tool using a JSON-formatted POST request."
  },
  "servers" : [ {
    "url" : "https://api.hubapi.com"
  } ],
  "tags" : [ {
    "name" : "Advanced"
  } ],
  "paths" : {
    "/marketing/v4/email/single-send" : {
      "post" : {
        "tags" : [ "Advanced" ],
        "summary" : "Send an email",
        "description" : "Send a template email to a specific recipient.",
        "operationId" : "post-/marketing/v4/email/single-send_/marketing/v4/email/single-send",
        "parameters" : [ ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/PublicSingleSendRequestEgg"
              },
              "example" : null
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/EmailSendStatusView"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "transactional-email" ]
        }, {
          "oauth2" : [ "marketing-email" ]
        } ],
        "x-hubspot-rate-limit-exemptions" : [ "daily", "ten-secondly" ]
      }
    }
  },
  "components" : {
    "schemas" : {
      "EmailSendStatusView" : {
        "required" : [ "status", "statusId" ],
        "type" : "object",
        "properties" : {
          "completedAt" : {
            "type" : "string",
            "description" : "Time when the send was completed.",
            "format" : "date-time",
            "example" : null
          },
          "eventId" : {
            "$ref" : "#/components/schemas/EventIdView"
          },
          "message" : {
            "type" : "string",
            "description" : "A human readable message describing the error along with remediation steps where appropriate",
            "example" : null
          },
          "requestedAt" : {
            "type" : "string",
            "description" : "Time when the send was requested.",
            "format" : "date-time",
            "example" : null
          },
          "sendResult" : {
            "type" : "string",
            "description" : "Result of the send.",
            "example" : null,
            "enum" : [ "ADDRESS_LIST_BOMBED", "ADDRESS_ONLY_ACCEPTED_ON_PROD", "ADDRESS_OPTED_OUT", "ATTACHMENT_DOWNLOAD_QUEUE_FULL", "BLOCKED_ADDRESS", "BLOCKED_DOMAIN", "BRAND_RECIPIENT_FATIGUE_SUPPRESSED", "CAMPAIGN_CANCELLED", "CANCELLED_ABUSE", "CONTACT_VIEW_PERMISSION", "CORRUPT_INPUT", "EMAIL_DISABLED", "EMAIL_UNCONFIRMED", "GDPR_DOI_ENABLED", "GRAYMAIL_SUPPRESSED", "HUBL_LIMIT_EXCEEDED", "IDEMPOTENT_FAIL", "IDEMPOTENT_IGNORE", "INVALID_APP_ID_ATTRIBUTION", "INVALID_FROM_ADDRESS", "INVALID_TO_ADDRESS", "LOW_CONTACT_QUALITY_SCORE", "MARKETING_ACTIVATION_DISALLOWED", "MISSING_CONTENT", "MISSING_REQUIRED_PARAMETER", "MISSING_TEMPLATE_PROPERTIES", "MTA_IGNORE", "NON_MARKETABLE_CONTACT", "PORTAL_AUTHENTICATION_FAILURE", "PORTAL_EXPIRED", "PORTAL_MISSING_MARKETING_SCOPE", "PORTAL_NOT_AUTHORIZED_FOR_APPLICATION", "PORTAL_OVER_LIMIT", "PORTAL_SUSPENDED", "PREVIOUS_SPAM", "PREVIOUSLY_BOUNCED", "PREVIOUSLY_UNSUBSCRIBED_BRAND", "PREVIOUSLY_UNSUBSCRIBED_BUSINESS_UNIT", "PREVIOUSLY_UNSUBSCRIBED_MESSAGE", "PREVIOUSLY_UNSUBSCRIBED_PORTAL", "QUARANTINED_ADDRESS", "QUEUED", "RECIPIENT_FATIGUE_SUPPRESSED", "SENT", "TEMPLATE_RENDER_EXCEPTION", "THROTTLED", "TOO_MANY_RECIPIENTS", "UBB_GOVERNANCE_MISSING", "UNCONFIGURED_SENDING_DOMAIN", "UNDELIVERABLE", "VALIDATION_FAILED" ]
          },
          "startedAt" : {
            "type" : "string",
            "description" : "Time when the send began processing.",
            "format" : "date-time",
            "example" : null
          },
          "status" : {
            "type" : "string",
            "description" : "Status of the send request.",
            "example" : null,
            "enum" : [ "CANCELED", "COMPLETE", "PENDING", "PROCESSING" ]
          },
          "statusId" : {
            "type" : "string",
            "description" : "Identifier used to query the status of the send.",
            "example" : null
          }
        },
        "description" : "Describes the status of an email send request.",
        "example" : null
      },
      "Error" : {
        "required" : [ "category", "correlationId", "message" ],
        "type" : "object",
        "properties" : {
          "category" : {
            "type" : "string",
            "description" : "The error category",
            "example" : null
          },
          "context" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "array",
              "example" : null,
              "items" : {
                "type" : "string",
                "example" : null
              }
            },
            "description" : "Context about the error condition",
            "example" : "{invalidPropertyName=[propertyValue], missingScopes=[scope1, scope2]}"
          },
          "correlationId" : {
            "type" : "string",
            "description" : "A unique identifier for the request. Include this value with any error reports or support tickets",
            "format" : "uuid",
            "example" : "aeb5f871-7f07-4993-9211-075dc63e7cbf"
          },
          "errors" : {
            "type" : "array",
            "description" : "further information about the error",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/ErrorDetail"
            }
          },
          "links" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "string",
              "example" : null
            },
            "description" : "A map of link names to associated URIs containing documentation about the error or recommended remediation steps",
            "example" : null
          },
          "message" : {
            "type" : "string",
            "description" : "A human readable message describing the error along with remediation steps where appropriate",
            "example" : "An error occurred"
          },
          "subCategory" : {
            "type" : "string",
            "description" : "A specific category that contains more specific detail about the error",
            "example" : null
          }
        },
        "description" : "Represents an error response returned by the API when an operation fails. This component is used in various endpoints to provide detailed information about the error encountered.",
        "example" : {
          "message" : "Invalid input (details will vary based on the error)",
          "correlationId" : "aeb5f871-7f07-4993-9211-075dc63e7cbf",
          "category" : "VALIDATION_ERROR",
          "links" : {
            "knowledge-base" : "https://www.hubspot.com/products/service/knowledge-base"
          }
        }
      },
      "ErrorDetail" : {
        "required" : [ "message" ],
        "type" : "object",
        "properties" : {
          "code" : {
            "type" : "string",
            "description" : "The status code associated with the error detail",
            "example" : null
          },
          "context" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "array",
              "example" : null,
              "items" : {
                "type" : "string",
                "example" : null
              }
            },
            "description" : "Context about the error condition",
            "example" : "{missingScopes=[scope1, scope2]}"
          },
          "in" : {
            "type" : "string",
            "description" : "The name of the field or parameter in which the error was found.",
            "example" : null
          },
          "message" : {
            "type" : "string",
            "description" : "A human readable message describing the error along with remediation steps where appropriate",
            "example" : null
          },
          "subCategory" : {
            "type" : "string",
            "description" : "A specific category that contains more specific detail about the error",
            "example" : null
          }
        },
        "description" : "Represents detailed information about an error that occurred in the API. This component is used to provide additional context and specifics about errors, typically as part of an error response.",
        "example" : null
      },
      "EventIdView" : {
        "required" : [ "created", "id" ],
        "type" : "object",
        "properties" : {
          "created" : {
            "type" : "string",
            "description" : "Time of event creation.",
            "format" : "date-time",
            "example" : null
          },
          "id" : {
            "type" : "string",
            "description" : "Identifier of event.",
            "format" : "uuid",
            "example" : null
          }
        },
        "description" : "The ID of a send event.",
        "example" : null
      },
      "PublicSingleSendEmail" : {
        "required" : [ "to" ],
        "type" : "object",
        "properties" : {
          "bcc" : {
            "type" : "array",
            "description" : "List of email addresses to send as Bcc.",
            "example" : null,
            "items" : {
              "type" : "string",
              "example" : null
            }
          },
          "cc" : {
            "type" : "array",
            "description" : "List of email addresses to send as Cc.",
            "example" : null,
            "items" : {
              "type" : "string",
              "example" : null
            }
          },
          "from" : {
            "type" : "string",
            "description" : "The From header for the email.",
            "example" : null
          },
          "replyTo" : {
            "type" : "array",
            "description" : "List of Reply-To header values for the email.",
            "example" : null,
            "items" : {
              "type" : "string",
              "example" : null
            }
          },
          "sendId" : {
            "type" : "string",
            "description" : "ID for a particular send. No more than one email will be sent per sendId.",
            "example" : null
          },
          "to" : {
            "type" : "string",
            "description" : "The recipient of the email.",
            "example" : null
          }
        },
        "description" : "A JSON object containing anything you want to override.",
        "example" : null
      },
      "PublicSingleSendRequestEgg" : {
        "required" : [ "emailId", "message" ],
        "type" : "object",
        "properties" : {
          "contactProperties" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "string",
              "example" : null
            },
            "description" : "The contactProperties field is a map of contact property values. Each contact property value contains a name and value property. Each property will get set on the contact record and will be visible in the template under {{ contact.NAME }}. Use these properties when you want to set a contact property while you’re sending the email. For example, when sending a receipt you may want to set a last_paid_date property, as the sending of the receipt will have information about the last payment.",
            "example" : null
          },
          "customProperties" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "object",
              "properties" : { },
              "example" : null
            },
            "description" : "The customProperties field is a map of property values. Each property value contains a name and value property. Each property will be visible in the template under {{ custom.NAME }}.\nNote: Custom properties do not currently support arrays. To provide a listing in an email, one workaround is to build an HTML list (either with tables or ul) and specify it as a custom property.",
            "example" : null
          },
          "emailId" : {
            "type" : "integer",
            "description" : "The content ID for the email, which can be found in email tool UI.",
            "format" : "int64",
            "example" : null
          },
          "message" : {
            "$ref" : "#/components/schemas/PublicSingleSendEmail"
          }
        },
        "description" : "A request to send a single email asynchronously.",
        "example" : null
      }
    },
    "responses" : {
      "Error" : {
        "description" : "An error occurred.",
        "content" : {
          "*/*" : {
            "schema" : {
              "$ref" : "#/components/schemas/Error"
            },
            "example" : null
          }
        }
      }
    },
    "securitySchemes" : {
      "developer_hapikey" : {
        "type" : "apiKey",
        "name" : "hapikey",
        "in" : "query"
      },
      "oauth2" : {
        "type" : "oauth2",
        "flows" : {
          "authorizationCode" : {
            "authorizationUrl" : "https://app.hubspot.com/oauth/authorize",
            "tokenUrl" : "https://api.hubapi.com/oauth/v1/token",
            "scopes" : {
              "marketing-email" : "",
              "transactional-email" : ""
            }
          }
        }
      },
      "private_apps" : {
        "type" : "apiKey",
        "name" : "private-app",
        "in" : "header"
      },
      "private_apps_legacy" : {
        "type" : "apiKey",
        "name" : "private-app-legacy",
        "in" : "header"
      }
    }
  },
  "x-hubspot-product-tier-requirements" : {
    "marketing" : "ENTERPRISE",
    "sales" : "FREE",
    "service" : "FREE",
    "cms" : "FREE",
    "commerce" : "FREE",
    "crmHub" : "FREE",
    "dataHub" : "FREE"
  }
}