SMTPD
  • Introduction
    • What is transactional email?
    • Getting Started
    • FAQ
      • Email Deliverability
        • Sending Reputation
        • Spam Filters
        • Blocklist
        • Bounce Rates
        • Spam Complaints
      • Email Tracking
        • Open Tracking
        • Click Tracking
  • User Guide
    • Click Tracking
  • API
    • Create Account
    • Authentication
    • Sending Profile
    • [In beta] Email Templates
    • Forms
    • Send
    • Analysis
      • Engagement
      • Delivery
    • Account & Billing
      • Users
      • API Keys
      • Roles & Permissions
      • Billing & Usage
Powered by GitBook
On this page
  • Grant Token (Login)
  • Refresh Access Token
  • Revoke refresh token (Logout)
  • Get Me

Was this helpful?

  1. API

Authentication

PreviousCreate AccountNextSending Profile

Last updated 1 year ago

Was this helpful?

The SMTP API uses JWT bearer tokens to authenticate requests. You can view and manage your API keys via the .

Your JWT bearer tokens carry many privileges, so be sure to keep them secure! Do not share your tokens via publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via . Provide your API key as the basic auth username value. You do not need to provide a password.

If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer RPqH8iq9xHd7ayjQc2Qkg4j>jv/HUdWH" instead of -u RPqH8iq9xHd7ayjQc2Qkg4j>jv/HUdWH.

All API requests must be made over . Calls made over plain HTTP will fail. API requests without authentication will also fail.

Grant Token (Login)

POST https://api.smtpd.dev/oauth/token?grant_type=password

This endpoint allows you to login and retrieve your JWT access token & refresh token.

Headers

Name
Type
Description

Authorization

string

Basic: Base64(username:password) OR Base64(key:secret)

{
  "token_type": "bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50X2lkIjoiNDFkZmM2NTYtNWJmNi00YzgxLWI0ODUtZTcxMTFhNmEzMDQxIiwiZXhwIjoxNTk5MTI3OTU3LCJpZCI6IjQ4ZmFmNzEwLTc4MTgtNDk0ZC1hMjQ3LTIzZGI3MjFkNmZlYSIsImlzX2FjY291bnRfdmVyaWZpZWQiOmZhbHNlLCJpc3MiOiJTTVRQRCBJbmMiLCJuYW1lIjoiIiwic2NvcGUiOlsxXSwic3ViIjoiamFjay50cnVvbmdAamFtZXNoYXJkaWUuY29tIiwic3ViamVjdCI6ImphY2sudHJ1b25nQGphbWVzaGFyZGllLmNvbSJ9.lE0XewYrOZDCevHINLGodAQ8RJH5nSr9GnY60ZwqWfk",
  "expires_at": 1712531293539,
  "Scope": [
    "admin"
  ],
  "refresh_token": "6f4T4ws_JPkwCu9xOkul7ZkTxPyL_eB-6TFZBgITCyuV86r-yU7aF5Y4_8Y4Y7-4fzqstRDdaVX1R49ND-wkjXUMe4B3EXngkkP7sg_dP8nE7yuem3HF0sUmfVyiInhU"
}
{
  "code": 40102,
  "message": "Username and password are incorrect"
}

Refresh Access Token

POST https://api.smtpd.dev/oauth/token?grant_type=refresh_token

This endpoint allows you refresh your access token.

Request Body

Name
Type
Description

refresh_token

string

Refresh Token

{
  "token_type": "bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50X2lkIjoiNDFkZmM2NTYtNWJmNi00YzgxLWI0ODUtZTcxMTFhNmEzMDQxIiwiZXhwIjoxNTk5MTI4MjAzLCJpZCI6IjQ4ZmFmNzEwLTc4MTgtNDk0ZC1hMjQ3LTIzZGI3MjFkNmZlYSIsImlzX2FjY291bnRfdmVyaWZpZWQiOmZhbHNlLCJpc3MiOiJTTVRQRCBJbmMiLCJuYW1lIjoiIiwic2NvcGUiOlsxXSwic3ViIjoiamFjay50cnVvbmdAamFtZXNoYXJkaWUuY29tIiwic3ViamVjdCI6ImphY2sudHJ1b25nQGphbWVzaGFyZGllLmNvbSJ9.zUOD-Zf3mfcMF56ex5J__3KmWFNSKQrVyY5ZE28Uu3M",
  "expires_at": 1712531293539,
  "Scope": [
    "admin"
  ],
  "refresh_token": "6f4T4ws_JPkwCu9xOkul7ZkTxPyL_eB-6TFZBgITCyuV86r-yU7aF5Y4_8Y4Y7-4fzqstRDdaVX1R49ND-wkjXUMe4B3EXngkkP7sg_dP8nE7yuem3HF0sUmfVyiInhU"
}
{
  "code": 40106,
  "message": "Refresh token is invalid"
}

Revoke refresh token (Logout)

POST https://api.smtpd.dev/oauth/revoke

Headers

Name
Type
Description

Authentication

string

Bearer {access_token}

Request Body

Name
Type
Description

refresh_token

string

Refresh Token to be revoked

null
{
  "code": 40106,
  "message": "Refresh token is invalid"
}

Get Me

GET https://api.smtpd.dev/oauth/me

This endpoint returns the logged in users details.

Headers

Name
Type
Description

Authentication

string

Bearer {access_token}

{
  "id": "19ab52c7-da60-4dd2-af27-19f17d6afe37",
  "account_id": "811affc1-66c7-4982-b39e-29f9536b4720",
  "email_address": "jack.truong@jameshardie.com",
  "first_name": "Jack",
  "surname": "Truong",
  "gravatar_url": "",
  "is_owner": true,
  "is_verified": false,
  "created_at_utc": 1598610725000,
  "modified_at_utc": 1598610725000
}

auth API endpoints
HTTP Basic Auth
HTTPS