Create SMTP API Tokens

POST /email/public/v1/smtpapi/tokens

Method Details

HTTP Methods:

POST

Request Format:

JSON

Response Format:

JSON

Requires Authentication?

Yes

Rate Limited?

Yes

This endpoint is used to create an SMTP API Token. An API token provides both a username and password which can then be used to send email through the HubSpot SMTP API:

  • SMTP Hostname: smtp.hubapi.com
  • SMTP Port: 587 (for STARTTLS) or 465 (for TLS)
  • SMTP User Name: provided in the userName field
  • SMTP Password: provided in the password field

Once an SMTP API Token is created, it can be used to send emails and track events throughout the HubSpot product. Here are a few ways to use a token once created:

  • In the Email Campaign Data API you can use the emailCampaignId and appId fields
  • In the Email Event API you can get specific details about events that occurred for the email.
  • In Contacts dynamic list definitions, under "Email Event" you can search for a campaign name to dynamically update a contacts list based on events sent with the token.

Note that use of API requires the Transactional Email add-on.

Required Parameters How to use Description
Access Token Used in the request URL The HubSpot access token for the given portal
createdBy Used in the request JSON The email address of the user creating the token
campaignName Used in the request JSON A name for the campaign tied to the SMTP API token. Currently used in the List segmentation UI and the SMTP Token API.

Example CURL Request

curl -XPOST \ -H "Content-Type: application/json" \ -d '{"createdBy":"demo@hubspot.com","campaignName":"test Transactional Email"}' \ https://api.hubapi.com/email/public/v1/smtpapi/tokens?hapikey=demo

Example JSON Response

{
  "userName": "hrfdvt58el@62515.smtp.hubspot.net",
  "password": "3432fff8eljl1249fjjasdfnv3",
  "portalId": 62515,
  "emailCampaignId": 14862038,
  "createdAt": 1415660606232,
  "deleted": false,
  "createdBy": "maxiak@hubspot.com",
  "appId": 22709,
  "campaignName": "test Transactional Email"
}

SMTP API

After creating the token above, you can use SMTP to send an email:
  • SMTP Hostname: smtp.hubapi.com
  • SMTP Port: 587 (for STARTTLS) or 465 for TLS
  • SMTP User Name: hrfdvt58el@62515.smtp.hubspot.net
  • SMTP Password: 3432fff8eljl1249fjjasdfnv3

Email Campaign Data

After you send email, use the Email Campaign Data API to retrieve data for the specific token:
https://api.hubapi.com/email/public/v1/campaigns/14862038?appId=22709&hapikey=demo

Email Events Data

After sending email, use the Email Events API to get event data for the specific campaign:
https://api.hubapi.com/email/public/v1/events?campaignId=14862038&appId=22709&hapikey=demo