There's a new version of the HubSpot API

Check out the new API
View Beta Docs

We're also working on a new documentation website, you're invited to check it out and give us your feedback.

Create SMTP API Tokens

Last updated January 7, 2025

POST /email/public/v1/smtpapi/tokens

Method Details

HTTP Methods:

POST

Request Format:

JSON

Response Format:

JSON

Requires Authentication?

Yes

Rate Limited?

Yes

Required Scope

transactional-email

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
OAuth Access Token Authorization: Bearer {token}
Used in the request headers

Used to authenticate the request. Please see this page for more details about authentication.
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

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

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

About

Jobs

Learn Inbound

Support

Locations

HubSpot, Inc.
25 First Street, 2nd Floor
Cambridge, MA 02141
European Headquarters
Ground Floor, Two Dockland Central
Guild Street, Dublin 1
Asia/Pacific Office
20 Hunter St, Level 7
Sydney NSW 2000
View our other locations
{ "userName": "h...l@62515.smtp.hubspot.net", "password": "34...v3", "portalId": 62515, "emailCampaignId": 14845842, "createdAt": 1415660606232, "deleted": false, "createdBy": "test@hubspot.com", "appId": 22709, "campaignName": "TransactionalTest" }
import requests import urllib import json import smtplib def create_smtp_api_token(created_by, campaign_name, **params): if not (params.get('access_token')): raise Exception("Expecting access_token") data = json.dumps({ "createdBy": created_by, "campaignName": campaign_name }) headers={"content-type": "application/json", "Authorization": f"Bearer {params['access_token']}"} r = requests.post("https://api.hubapi.com/email/public/v1/smtpapi/tokens", data, headers=headers) if 200 <= r.status_code < 300: return r.json() else: raise Exception("Unknown error with HubSpot API: code:{0}, response:{1}".format(r.status_code, r.content)) FROM_EMAIL = "sender@example.com" TO_EMAIL = "recipient@example.com" def send_test_email(smtp_api_token): server = smtplib.SMTP("smtp.hubapi.com", 587) server.starttls() server.login(smtp_api_token['userName'], smtp_api_token['password']) msg = "From: {from_}\r\nTo: {to}\r\nSubject: {subject}\r\n\r\n{body}".format( from_=FROM_EMAIL, to=TO_EMAIL, subject='HubSpot SMTP API Test', body='text' ) server.sendmail(FROM_EMAIL, [TO_EMAIL], msg) server.quit() print ("Enqueued email send to {to} for campaignId: {campaignId}, appId: {appId}".format( to=TO_EMAIL, campaignId=smtp_api_token['emailCampaignId'], appId=smtp_api_token['appId'] )) smtp_api_token = create_smtp_api_token("email address of creator", "test transactional email", access_token="YOUR_ACCESS_TOKEN") send_test_email(smtp_api_token)
$ 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 { "portalId": 62515, "userName": "t...s@62515.smtp.hubspot.net", "password": "Su...WN", "passwordHash": null, "emailCampaignId": 14861198, "createdAt": 1415741149655, "deleted": false, "createdBy": "demo@hubspot.com", "appId": 22709, "campaignName": "test Transactional Email" }