Marketing Email Overview

This API can be used to programmatically create marketing emails, get details about marketing emails, and update marketing emails. Additionally, this API features two endpoints that return email send related statistics. These statistics are identical to what you can access in app under the details section of a particular email and will be returned under the stats object in your json response.

The Marketing Email API refers to marketing emails. It is important to note that this API does not apply to sales emails that are created and sent on contact records. To get details for sales emails you can use the Engagements API

Note: you will not be able to send emails through this API. If you would like to programmatically send emails, please refer to the single send API.

Note: The example below does not include the stats object. Please see the stats specific pages for a description of the email statistics fields.

Each Marketing email has the following data:

{
  "ab": true,
  // Boolean; Whether or not the page is part of an AB test.
  "abHoursToWait": 4,
  // integer; on AB emails, if test results are inconclusive after 4 hours, variation A will be sent.
  "abVariation": false,
  // Boolean; Whether or not the page is the variation (as opposed to the master) if the page is part of an AB test
  "abSampleSizeDefault": "MASTER",
  // String; ["MASTER", "VARIANT"] if there are less than 1000 recipients, only one variation will be sent.
  "abSamplingDefault": "MASTER", 
  // String; ["MASTER", "VARIANT"] if AB test results are inconclusive in the test group, choose a variation to send (resp. A or B) to the remaining contacts.
  "abStatus": "MASTER",
  // String; ["MASTER", "VARIANT"] determines if the current email is variation A or variation B.
  "abSuccessMetric": "CLICKS_BY_OPENS",
  // String; [ CLICKS_BY_OPENS, CLICKS_BY_DELIVERED, OPENS_BY_DELIVERED ] metric that will be used to determine the winning variation.
  "abTestId": "1234567890",
  // String; id shared between variation A and B
  "abTestPercentage": 40,
  // Integer; the size of the test group (40% will receive variation A, the other 60% variation B).
  "abVariation": false,
  // Boolean; Determines whether the email is a variant or not.
  "absoluteUrl":"http://your-website.hs-sites.com/web-version",
  // String; The URL of the web version of the email.
  "allEmailCampaignIds": [],
  // A list of email IDs that are associated with the email. 
  "analyticsPageId": "1234567890",
  // String; the id used to access the analytics page of the email(in most cases, the same as the email ID)
  "analyticsPageType": "email",
  // String["blog-post", "email", "knowledge-article", "site-page", "landing-page"] always "email" for an email
  "archived": false,
  // Boolean; determines whether the email is archived or not.
  "author": "test@hubspot.com",
  // String; the email of the user who made the last update to the email. 
  "authorAt": 1516383316944,
  // Integer; timestamp of the last update to the email in milliseconds.
  "authorEmail": "test@hubspot.com",
  // String; the email of the user who made the last update to the email.
  "authorName": "Test Testeron",
  // String; the name of the user who made the last update to the email.
  "authorUserId": 1234567,
  // Integer; id of the user who made the last update to the email.
  "blogEmailType": "daily",
  // String; ["instant", "daily", "weekly", "monthly"] the cadence for how often blog emails should be sent.
  "blogRssSettings": null,
  // { blogLayout: [0=summary, 1=summary with featured image, 2=full post} ] additional settings for blog subscription emails.
  "campaign": "eeeeeeee-eeee-eeee-eeee",
  // String; the ID of an email's marketing campaign.
  "campaignName": "Sample - My first inbound campaign in HubSpot",
  // String; the name of the email's marketing campaign.
  "canSpamSettingsId": 1234567890,
  // Integer; ID used to retrieve the company address, shown in the footer.
  "categoryId": 2,
  // Integer; the category ID value, which is always 2 for emails (read only).
  "clonedFrom": 1234567890,
  // Integer; if the email was cloned, ID of the email it was cloned from.
  "contentTypeCategory": 2,
  // Integer; the category ID value, which is always 2 for emails (read only).
  "createPage": false,
  // Boolean; enables a web version of the email when set to true. 
  "created": 1514293429917,
  // Integer; the timestamp of the email's creation, in milliseconds. 
  "currentlyPublished": false,
  // Boolean; determines the publish status of the email. 
  "domain": "",
  // String; the domain of the web version of the email. Defaults to the primary domain. 
  "emailBody": "Example email body",
  // String; the main content of the email within the 'main email body' module.
  "emailNote": "Example email note",
  // String; optional email notes, included in the details page of the email. 
  "emailType": "BLOG_EMAIL",
  // String;[ BATCH_EMAIL, AB_EMAIL, AUTOMATED_EMAIL, BLOG_EMAIL, BLOG_EMAIL_CHILD, FOLLOWUP_EMAIL, LOCALTIME_EMAIL, OPTIN_EMAIL, OPTIN_FOLLOWUP_EMAIL, RESUBSCRIBE_EMAIL,
  // RSS_EMAIL, RSS_EMAIL_CHILD, SINGLE_SEND_API, SMTP_TOKEN, LEADFLOW_EMAIL, FEEDBACK_CES_EMAIL, FEEDBACK_NPS_EMAIL, FEEDBACK_CUSTOM_EMAIL, TICKET_EMAIL ]
  "feedbackEmailCategory": null,
  // String; [ "NPS, "CES", "CUSTOM" ] If the email is a feedback email, determines type of feedback email.
  "feedbackSurveyId": null,
  // Integer; the id of the feedback survey that is linked to the email.
  " flexAreas": {},
  // Describes the layout of the drag and drop email template.
  "folderId": 1234567890,
  // Integer; if the email is in a folder, id of that folder.
  "freezeDate": 1516383316944,
  // Integer; The publish date or updated date if the email is not published.
  "fromName": "Sample Author",
  // String; the sender name recipients will see (linked to the replyTo address).
  "htmlTitle": "",
  // String; the page title of the web version of the email.
  "id": 1234567890,
  // Integer; the id of the email.
  "isGraymailSuppressionEnabled": true,
  // Boolean; if true, the email will not send to unengaged contacts. 
  "isLocalTimezoneSend": false,
  // Boolean; if true, the email will adjust its send time relative to the recipients timezone. 
  "isPublished": false,
  //Boolean; if true, the email is in a published state. 
  "isRecipientFatigueSuppressionEnabled": null,
  // Boolean; if true, enables a send frequency cap (a feature available to enterprise accounts).
  "leadFlowId": null,
  // Integer; the id of the parent leadflow if the email is a leadflow email. 
  "liveDomain": "your-website.hs-sites.com",
  // String; domain actually used in the web version (read only)
  "mailingListsExcluded": [],
  // A list of all contact lists to exclude from the email send. 
  "mailingListsIncluded": [],
  //A list of all contact lists included in the email send. 
  "maxRssEntries": 5,
  // in blog and recurring emails, the max number of entries to include. 
  "metaDescription": "",
  // String; meta description of the web version of the email, to drive search engine traffic to your page
  "name": "Daily notification email for blog \"Default HubSpot Blog\"",
  // String; the name of the email, as displayed on the email dashboard. 
  "pageExpiryDate": 1548464400000,
  // Integer; the expiration date of the web version of an email, in milliseconds.
  "pageExpiryRedirectId": 0,
  // String; the url of the page the user will be redirected to after the web version of the email expires.
  "pageRedirected": false,
  // Boolean; indicates if the email's web version has already been set to redirect
  "portalId": 12345,
  // Integer; the id of the parent portal. 
  "previewKey": "abcDEFgH",
  // String; the preview key used to generate the preview url before the email is published
  "processingStatus": "",
  // String; [ UNDEFINED, PUBLISHED, PUBLISHED_OR_SCHEDULED, SCHEDULED, PROCESSING,
  // PRE_PROCESSING, ERROR, CANCELED_FORCIBLY, CANCELED_ABUSE ]
  // the email's processing status.
  "publishDate": 1514293429917,
  // Integer; the timestamp in milliseconds that the email has been published at, or scheduled to send at. 
  "publishedAt": 1514293429917,
  // Integer; if the email has been published, the time when the publish button has been pressed.
  "publishedById": 1234567,
  // Integer; if the email has been published, email of the user that pressed the publish button (read only).
  "publishedByName": "Test Testerson",
  // String; if the email has been published, name of the user that pressed the publish button (read only).
  "publishImmediately" : true,
  // Boolean; true if the email is not scheduled but will send at publish time.
  "publishedUrl": "",
  // String; absoluteUrl, only if the email is currentlyPublished (read-only),
  "replyTo": "SampleAuthor@hubspot.com",
  // String; The email address the recipient will see and reply to (linked to fromName).
  "resolvedDomain": "your-website.hs-sitesqa.com",
  // String; the domain used in the web version: either the primary one or the one set in the domain field (read only)
  "rssEmailAuthorLineTemplate": "By , ",
  // String; text shown before the "author_line" tag in blog & RSS email's items.
  "rssEmailBlogImageMaxWidth" : 300,
  // Integer; the max width for blog post images in RSS emails. 
  "rssEmailByText": "By",
  // String; if rssEmailAuthorLineTemplate is not set, word before the author name in blog & RSS email's items.
  "rssEmailClickThroughText": "Read more",
  // String; text shown on the link to see the full post in blog & RSS email's items.
  "rssEmailCommentText": "Comment;",
  // String; text shown on the link to comment the post in blog & RSS email's items.
  "rssEmailEntryTemplate": "",
  // String; optional, custom template for every RSS entry.
  "rssEmailEntryTemplateEnabled": false,
  // Boolean; determines if the Entry Template is used for an RSS email. 
  "rssEmailUrl": "",
  // String; URL used for social sharing. 
  "rssToEmailTiming": {
     "repeats": "daily", // [ "instant", "daily", "weekly", "monthly" ]
     "repeats_on_monthly": 1, // what day of the month should the monthly email be sent [1-31]
     "repeats_on_weekly": 1, // what day of the week should the weekly email be sent [1=monday - 7=sunday]
     "summary": "Daily", // description, not used
     "time": "9:00 am" // time the email should be sent at
  },
  // A dictionary that determines what time the RSS email should be sent out. 
  "slug": "web-version",
  // String; path of the web version URL. 
  "smartEmailFields": null,
  // String; lists the smart objects in email fields (from address, subject..)
  "styleSettings": null,
  // String; Custom email style settings (background color, primary font);
  "subcategory": "blog_email",
  // [ ab_master, ab_variant, automated, automated_for_deal, automated_for_form, automated_for_form_legacy, automated_for_form_buffer, automated_for_form_draft,
  // rss_to_email, rss_to_email_child, blog_email, blog_email_child, optin_email, optin_followup_email, batch, resubscribe_email, single_send_api, smtp_token,
  // localtime, automated_for_ticket, automated_for_leadflow, automated_for_feedback_ces, automated_for_feedback_nps, automated_for_feedback_custom ]
  "subject": "New Posts today for the blog Default HubSpot Blog",
  // String; the subject of the email. 
  "subscription": 123456,
  // Integer; the id of the email's subscription type.
  "subscriptionBlogId": 1234567890,
  // Integer; for blog emails, id of the linked blog.
  "subscription_name": "Default HubSpot Blog Subscription",
  // String; the name of the email's subscription type.
  "templatePath": "generated_layouts/1234567890.html",
  // String; the path of the email's body template within the design manager. 
  "transactional": false,
  // Boolean; determines whether the email is a transactional email or not. 
  "unpublishedAt": 0,
  // Integer; the timestamp in milliseconds of when the email was unpublished.
  "updated": 1516383316944,
  // Integer; timestamp of the last update in milliseconds.
  "updatedById": 1234567,
  // Integer; the ID of the last user who updated the email. 
  "url": "http://your-website.hs-sites.com/web-version",
  // String; the web version URL (read-only).
  "useRssHeadlineAsSubject": false,
  // Boolean; Setting for RSS emails, uses the latest RSS entry as the email subject.
  "vidsExcluded": [],
  // A list of contact IDs to exclude from being sent the email. 
  "vidsIncluded": [],
  // A list of contacts IDs to include in the email send. 
  "widgets": {},
  // The content of layout sections of the email (widgets).
  "workflowNames": []
  // a list of all linked workflows to this email. 
  }
 

Marketing Email API docs

How can we improve our API status reporting?

If you have a few minutes, we would love to hear your thoughts.
Give Feedback