# Introduction

Welcome to the SMTPD docs


# What is transactional email?

Transactional emails are system-triggered emails sent to a user by a company’s app or website based on that specific user’s activity. As consumers, we interact with these emails almost on a daily basis: password resets, order confirmations, login details, shipping notifications, flight confirmations, cart abandonment alerts, and more.

Examples of transactional emails include purchase receipts, account verification emails, password reset emails, and shipping confirmation emails. Transactional emails are typically sent to a smaller audience than promotional or marketing emails, and they are often considered to be more important or time-sensitive.

Transactional emails differ from promotional or marketing emails in that they are not primarily intended to promote a product or service, but rather to provide information or facilitate a transaction. As a result, transactional emails are generally less likely to be marked as spam and have a higher deliverability rate.

Due to the critical content inside these emails, transactional emails are the most highly engaged emails that businesses send. Research shows transactional emails [have 8x more opens and clicks](http://www.experian.com/assets/marketing-services/reports/transactional-email-report.pdf) than any other type of email, and can [generate 6x more revenue](http://www.experian.com/assets/marketing-services/reports/transactional-email-report.pdf). This makes sense when you think about the last time you received a flight confirmation, for example: You probably bookmarked the email, re-opened it several times before the flight, and may have even printed it or forwarded it to your family and friends.

{% hint style="info" %}
 Do you know how many types of transactional emails your business/app sends?
{% endhint %}


# Getting Started

Welcome to SMTPD! 

Before you can start using the SMTPD you'll need to create an account. 

You can do that directly via the API of from our sign-up form at <https://app.smtpd.dev/signup>.&#x20;

Once you've created an account all features are automatically enabled *except* sending, which requires verifcation from our support team. They will reach our via email to confirm your details before sending is enabled.

Our API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer), has predictable resource-oriented URLs, accepts [JSON-encoded](http://www.json.org/) request bodies, returns [JSON-encoded](http://www.json.org/) responses, and uses standard HTTP response codes, authentication, and verbs.

Before you can use the SMTPD REST APIs, you will need to have a valid API key.&#x20;

**IMPORTANT!** Make sure to copy and paste the API key when it is displayed after saving. The whole API key is shown **ONE TIME ONLY**. After navigating away from that page recovery of a lost key is impossible. Keep your API keys in a safe and secure place. Treat them like passwords and never share them with anyone.


# FAQ


# Email Deliverability

Email deliverability refers to the ability of an email message to reach the intended recipient's inbox. It is important because it determines whether or not the recipient will see and be able to read the message.

There are several factors that can impact email deliverability, including the sending reputation of the sender, the content of the message, the structure of the message, and the email server or provider being used.

To improve email deliverability, it is important to follow best practices when sending email. This includes using a reputable email service provider, obtaining permission from recipients before sending them emails, using a double opt-in process for subscription emails, and following the guidelines of the CAN-SPAM Act in the United States. It is also important to maintain a clean email list and avoid sending spam or unsolicited emails.

There are several key concepts related to email deliverability that are important to understand:

1. [Sender reputation](/master/faq/email-deliverability/sending-reputation): The sending reputation of an email sender is a measure of the quality of their email practices. It is based on a variety of factors, including the number of bounces, spam complaints, and unsubscribes that an email sender has received. A high sending reputation can improve the deliverability of emails, while a low sending reputation can decrease deliverability.
2. [Spam filters](/master/faq/email-deliverability/spam-filters): Spam filters are used by email providers to identify and block unwanted or spam emails from reaching users' inboxes. Email messages that trigger certain spam filter criteria, such as using certain words or phrases, may be marked as spam and delivered to the recipient's spam folder instead of their inbox.
3. [Blocklists](/master/faq/email-deliverability/blocklist): Blocklists are lists of IP addresses and domains that are known to send spam or unsolicited emails. If an email sender's IP address or domain is on a blocklists, their emails may be blocked or flagged as spam by email providers.
4. [Bounce rates](/master/faq/email-deliverability/bounce-rates): Bounce rates refer to the percentage of emails that are not delivered to their intended recipients. There are two types of bounces: hard bounces and soft bounces. Hard bounces occur when an email cannot be delivered due to a permanent error, such as an invalid email address. Soft bounces occur when an email cannot be delivered due to a temporary error, such as a full mailbox.
5. [Spam complaints](/master/faq/email-deliverability/spam-complaints): Spam complaints occur when a recipient marks an email as spam. High spam complaint rates can negatively impact an email sender's reputation and deliverability.


# Sending Reputation

Sending reputation is a measure of the quality of an email sender's practices. It is based on a variety of factors, including the number of bounces, spam complaints, and unsubscribes that an email sender has received. A high sending reputation can improve the deliverability of emails, while a low sending reputation can decrease deliverability.

Email providers use sending reputation to determine whether or not to deliver emails to a recipient's inbox. If an email sender has a high sending reputation, their emails are more likely to be delivered to the recipient's inbox. If an email sender has a low sending reputation, their emails may be flagged as spam or delivered to the recipient's spam folder.

There are a number of things that can negatively impact an email sender's reputation, including:

* Sending a high volume of bounced or undeliverable emails
* Having a high number of spam complaints
* Sending emails to unengaged recipients or recipients who have not given permission to receive emails
* Using deceptive subject lines or header information

To improve your sending reputation, it is important to follow best practices when sending email. This includes obtaining permission from recipients before sending them emails, using a double opt-in process for subscription emails, maintaining a clean email list, and following the guidelines of the CAN-SPAM Act in the United States.


# Spam Filters

Spam filters are software programs that are designed to identify and block unwanted emails, also known as spam, from reaching a user's inbox. These filters use various techniques to identify spam emails, such as analyzing the content of the message, the sender's reputation, and the presence of certain keywords or phrases.

One common technique used by spam filters is to compare the content of the email to a list of known spam keywords or phrases. If the email contains any of these keywords or phrases, it is more likely to be classified as spam.

Spam filters may also use machine learning algorithms to analyze the content of emails and identify patterns that are common in spam emails. These patterns can include the use of certain words or phrases, the use of non-standard formatting, or the presence of links to suspicious websites.

In addition to analyzing the content of emails, spam filters may also consider the reputation of the sender. For example, if the sender has a history of sending spam emails, the filter may be more likely to classify their emails as spam.

Overall, the goal of a spam filter is to protect users from unwanted or potentially harmful emails by identifying and blocking spam before it reaches the user's inbox.


# Blocklist

A blocklist is a list of items, such as email addresses or IP addresses, that are considered undesirable or untrustworthy. Blocklist are commonly used to block unwanted emails, prevent access to certain websites, or block certain types of network traffic.

One common use of blocklist is in email systems, where a Blocklist is a list of email addresses or domains that are known to send spam or malicious emails. Email servers can use blacklists to identify and block emails from these sources, helping to protect users from receiving unwanted or potentially harmful emails.

Blocklist may also be used to block access to certain websites or types of content. For example, an organization may maintain a blocklist of websites that are known to host inappropriate or malicious content, and use this blacklist to block access to these sites from their network.

Blocklist may be maintained by organizations or individuals, and may be shared with others to help identify and block unwanted or untrustworthy items. However, it is important to note that blocklist are not always accurate or up-to-date, and some items may be mistakenly added to a blocklist or remain on a blocklist after the issue that led to their inclusion has been resolved.


# Bounce Rates

Bounce rate is a website metric that measures the percentage of visitors who leave a website after viewing only one page. A high bounce rate typically indicates that visitors are not finding the information or content they were looking for on the website, or that the website is not meeting their expectations. A low bounce rate, on the other hand, typically indicates that visitors are finding the website useful and are interacting with it.

There are many factors that can contribute to a high bounce rate, such as a poorly designed website, slow loading times, confusing navigation, or irrelevant or low-quality content. On the other hand, a well-designed website with clear and useful information, fast loading times, and a user-friendly navigation structure can help to reduce the bounce rate.

In general, it is important to monitor the bounce rate of a website and try to optimize it, as a high bounce rate can have a negative impact on the website's traffic and search engine rankings. However, it is also important to keep in mind that there are many factors that can affect bounce rate, and it is not always possible or desirable to achieve a low bounce rate in every situation.


# Spam Complaints

Spam complaints refer to the number of times that recipients of an email report it as spam or unsolicited email. Spam complaints are a measure of the effectiveness of an email marketing campaign, as they indicate that the recipients do not want to receive the emails and are taking action to report them as spam.

Spam complaints can have a negative impact on the reputation of the sender and the deliverability of their emails. Email providers and spam filters use various signals, including the number of spam complaints, to determine whether an email should be delivered to the recipient's inbox or sent to the spam folder. As a result, a high rate of spam complaints can lead to emails from the sender being blocked or filtered as spam, which can reduce the effectiveness of the email marketing campaign.

To avoid spam complaints, it is important to follow best practices for email marketing, such as obtaining explicit permission from recipients to send them emails, providing a clear and easy way to unsubscribe from the email list, and ensuring that the emails are relevant and useful to the recipients.


# Email Tracking

Email tracking is a feature that allows you to monitor the delivery and engagement of emails sent through SMTPD. This can help you understand how your emails are being received and used by recipients, and can provide valuable insights for improving the effectiveness of your email campaigns.

There are a few different ways that email tracking can be implemented:

1. [Open tracking](/master/faq/email-tracking/open-tracking): This tracks when an email is opened by a recipient. This is typically done by including a transparent image in the email that is loaded from SMTPD platform.
2. [Click tracking](/master/faq/email-tracking/click-tracking): This tracks when a recipient clicks on a link in an email. This is typically done by redirecting the link through the SMTPD platform, which allows the platform to track the click and record it in the email's tracking data.

Tracking data is usually accessible through SMTPD's API or App. This data can be used to understand how your emails are performing and to make informed decisions about how to improve their effectiveness.


# Open Tracking

Open tracking is a feature that allows you to track when an email is opened by a recipient. This implemented by including a transparent GIF image in the email that is loaded from the SMTPD platform when the email is opened.

Here's how it works:

1. When you send an email with open tracking enabled, the SMTPD platform inserts a transparent GIF image into the email. This image is hosted on the SMTPD platform and is  very small (a few bytes in size).
2. When the recipient opens the email, their email client will download the image from the SMTPD platform. This download request includes information about the recipient's email client and IP address, which is recorded by SMTPD.
3. The SMTPD platform uses this information to determine that the email has been opened and records this event in the email's tracking data.

Open tracking can be useful for understanding how your emails are being received and used by recipients. For example, you might use open tracking to understand how many of your emails are being opened, or to see how long it takes for an email to be opened after it is sent.&#x20;

{% hint style="info" %}
It's important to note that open tracking is not always accurate, as some email clients may block the tracking image or the recipient may have image loading disabled in their email clien
{% endhint %}


# Click Tracking

Click tracking is a feature that allows you to track when a recipient clicks on a link in an email. This is implemented by redirecting the link through the SMTPD platform, which stores the recipient tracking data.

Here's how it works:

1. When you send an email with click tracking enabled, the SMTPD platform modifies the links in the email by redirecting them through the platform.
2. When the recipient clicks on a link, their browser sends a request to the SMTPD platform to follow the redirected link.
3. The SMTPD platform records the click in the email's tracking data and then redirects the recipient's browser to the intended destination of the link.

Click tracking can be useful for understanding how your emails are being used by recipients. For example, you might use click tracking to see which links in your emails are being clicked the most, or to understand how long it takes for a recipient to click on a link after receiving an email.&#x20;

{% hint style="info" %}
It's important to note that some email clients or browsers may block click tracking, which could affect the accuracy of the tracking data.
{% endhint %}


# User Guide


# Click Tracking

#### What is Link Tracking?<br>

Like Open Tracking, Click Tracking is a method of collecting valuable information about how your recipients interact with the emails you send. Click Tracking is limited to HTML content, and does not rely on the user allowing images in their email client. Any tracked link that the user clicks on will record statistics. Click Tracking can also provide helpful diagnostics, such as determining if a particular recipient has clicked a link that was emailed to them.

#### How does it work?&#x20;

When Click Tracking has been enabled, links in your messages will be replaced with new links that route through your SMTPD sending profile `link_domain`. When an email recipient clicks on a tracked link, the URL is opened in their default browser. The browser will request the URL from the SMTPD platform, at which point we record information about the user's location & what device / browser they are using. While we record this information, we simultaneously redirect the user to the original URL in your email. The branded URL the user will see is based on your sending profile `link_domain`.

Links tracked by SMTPD do not expire. Since services like Gmail retain emails for *years,* it's possible that your recipients may search for and follow links for a long time into the future. Each tracked link issued by SMTPD contains all the necessary information to redirect to the original URL, even if you delete your SMTPD sending profile, so the link you send to your recipients will continue to work for the foreseeable future. Our redirection infrastructure is also globally distributed and redundant, and we built it with the goal of making sure the link redirection is as transparent and fast as possible for your recipients.

#### Link Security

All links tracked by the SMTPD platform are routed through our servers using HTTPS/TLS. Unlike other link tracking services that use non-encrypted HTTP connections, we ensure that eavesdroppers cannot capture the links sent to your recipients due to the redirection link using a non-encrypted HTTP URL. Transactional emails tend to contain recipient-specific links, so having "full-time" HTTPS for Tracked Links is an important protection that we believe is essential for your most important emails.

#### Requirements&#x20;

**Account Approval & Sending Profile verification**

One of the pre-requisites for using our link tracking system is that you have created an account and gone through our normal account approval process & correctly setup a sending profile - all emails used branded urls which are defined in a sending profile `link_domain`. ***Until your account is approved & a sending profile has been validated no emails will be accepted for sending OR encoded/tracked when sending emails.***

**Proper encoding**

Links must be properly encoded for both text and HTML. Including the following requirements:

* Links must be well-formed, according to [RFC-3986](https://tools.ietf.org/html/rfc3986).
* Links in HTML `a` elements must be HTML-encoded. We *automatically HTML-decode the URLs when processing your HTMLBody*.&#x20;
* Links must be properly [URL-encoded](https://en.wikipedia.org/wiki/Percent-encoding).
* Links must include a `http` or `https` protocol to be properly tracked.

Please note that if a link that is in an email message is malformed or improperly URL-encoded, we will skip replacing it with a tracked link. This ensures that only links that can be redirected using http-level redirects will be issued by SMTPD.

**Only HTTP and HTTPS are supported**

There are many protocols that can be used with links (i.e. `ftp://`,`ssh://`,`mailto:`, etc.). Currently only `http` and `https` links will be encoded and tracked by the SMTPD platform.

#### Enabling Link Tracking

**Click Tracking Options**

There are several variations of Click Tracking available, depending on your requirements, you can choose from the following options:

* `none` - No links will be replaced or tracked. This is the default setting for all messages.
* `click_tracking` - Links will be replaced in the send `content_html` field. You can set the `click_tracking` property on each message you [send through the API](/api/send).&#x20;

**Per-link opt-out**

In some cases you may wish to exclude a link from tracking, even if the rest of the message's links should be tracked. To do this, you should add an additional `data-smtpd-no-track` attribute to your links in the `content_html` of your message. For example:

`<a data-smtpd-no-track href="http://example.com"> Non-Tracked Link </a>`

*Note that this feature requires that the link be contained and ignored in HTML.*


# Create Account

You can signup to SMTPD via the api endpoint OR via <https://app.smtpd.dev/signup>

## Signup and create an SMTPD account

<mark style="color:green;">`POST`</mark> `https://api.smtpd.dev/api/v1/account`

This endpoint allows you to create and SMTPD account, once the account has been created someone from SMTPD will contact you to manually verify the account before you can send email.

#### Request Body

| Name           | Type    | Description                                                          |
| -------------- | ------- | -------------------------------------------------------------------- |
| terms          | boolean | Agree to our terms of service - <https://smtpd.dev/terms-of-service> |
| full\_name     | string  | Full name of the root user.                                          |
| plan\_id       | string  | Plan UUID from `/api/v1/billing/plans` endpoint.                     |
| country        | string  | The ISO 3166-1 3 letter country code for the account's location.     |
| password       | string  | The root user password.                                              |
| email\_address | string  | The email address of the root user for the account.                  |
| account\_name  | string  | The company OR person's name for the account.                        |

{% tabs %}
{% tab title="202 Account successfully enqueued for creation. Once the account has been created it will be manually verified." %}

```
{
  "account_id": "b1428eeb-2d55-4363-954e-a050bce8164e"
}
```

{% endtab %}
{% endtabs %}


# Authentication

The SMTP API uses JWT bearer tokens to authenticate requests. You can view and manage your API keys via the [auth API endpoints](/api/account/api-keys).

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 [HTTP Basic Auth](http://en.wikipedia.org/wiki/Basic_access_authentication). Provide your API key as the basic auth username value. You do not need to provide a password.&#x20;

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`.

{% hint style="info" %}
All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP will fail. API requests without authentication will also fail.
{% endhint %}

## Grant Token (Login)

<mark style="color:green;">`POST`</mark> `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)` |

{% tabs %}
{% tab title="200 Existing Refresh Tokens are expired when a new Grant Token is successful. Refresh Tokens have an absolute lifespan of 30 days" %}

```
{
  "token_type": "bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhY2NvdW50X2lkIjoiNDFkZmM2NTYtNWJmNi00YzgxLWI0ODUtZTcxMTFhNmEzMDQxIiwiZXhwIjoxNTk5MTI3OTU3LCJpZCI6IjQ4ZmFmNzEwLTc4MTgtNDk0ZC1hMjQ3LTIzZGI3MjFkNmZlYSIsImlzX2FjY291bnRfdmVyaWZpZWQiOmZhbHNlLCJpc3MiOiJTTVRQRCBJbmMiLCJuYW1lIjoiIiwic2NvcGUiOlsxXSwic3ViIjoiamFjay50cnVvbmdAamFtZXNoYXJkaWUuY29tIiwic3ViamVjdCI6ImphY2sudHJ1b25nQGphbWVzaGFyZGllLmNvbSJ9.lE0XewYrOZDCevHINLGodAQ8RJH5nSr9GnY60ZwqWfk",
  "expires_at": 1712531293539,
  "Scope": [
    "admin"
  ],
  "refresh_token": "6f4T4ws_JPkwCu9xOkul7ZkTxPyL_eB-6TFZBgITCyuV86r-yU7aF5Y4_8Y4Y7-4fzqstRDdaVX1R49ND-wkjXUMe4B3EXngkkP7sg_dP8nE7yuem3HF0sUmfVyiInhU"
}
```

{% endtab %}

{% tab title="403 " %}

```
{
  "code": 40102,
  "message": "Username and password are incorrect"
}
```

{% endtab %}
{% endtabs %}

## Refresh Access Token

<mark style="color:green;">`POST`</mark> `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 |

{% tabs %}
{% tab title="200 " %}

```
{
  "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"
}
```

{% endtab %}

{% tab title="403 " %}

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

{% endtab %}
{% endtabs %}

## Revoke refresh token (Logout)

<mark style="color:green;">`POST`</mark> `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 |

{% tabs %}
{% tab title="200 " %}

```
null
```

{% endtab %}

{% tab title="401 " %}

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

{% endtab %}
{% endtabs %}

## Get Me

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/oauth/me`

This endpoint returns the logged in users details.

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 " %}

```
{
  "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
}
```

{% endtab %}
{% endtabs %}


# Sending Profile

Your sending profile is used to manage email authentication such as DKIM, DMARC and SPF along with branded link URLs and bounce addresses. SMTPD has an opinionated sending setup that brings better deliverability.

{% hint style="warning" %}
Sending Profiles are critical to email deliverability and are continuously validated by the SMTPD platform. If any DNS records are removed OR incorrectly altered, your sending profile will be set into a "pending" and all sending will fail for any messages linked to that sending profile.
{% endhint %}

## Create sending profile

<mark style="color:green;">`POST`</mark> `https://api.smtpd.dev/api/v1/profile/email`

This endpoint allows you to create a new sending profile, you can add as many sending profiles as needed. Every sending profile is continuously validated, if any DNS records are missing the sending profile will be placed into a `pending` state, if that remains for longer than 72hrs the sending profile will be disabled and eventually deleted.&#x20;

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

#### Request Body

| Name                            | Type   | Description                                           |
| ------------------------------- | ------ | ----------------------------------------------------- |
| link\_domain\_default\_redirect | string | The default redirect destination for the link\_domain |
| bounce\_domain                  | string | The reply-to address domain                           |
| link\_domain                    | string | The domain used for the branded links                 |
| sending\_domain                 | string | The domain used in the "from address"                 |
| profile\_name                   | string | The name of the Sending Profile                       |

{% tabs %}
{% tab title="202 You new sending profile has been enqueued for creation. You'll need to poll the GET setup endpoint with the `profile_id` to receive the DNS records once creation has completed." %}

```
{
  "profile_id": "d1378ab7-e919-11ea-81e4-0a58a9feac2a",
  "profile_name": "default",
  "state": "creating"
}
```

{% endtab %}
{% endtabs %}

## Get sending profile domain setup details

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/profile/email/:id/setup`

This endpoint allows you to get the sending profile domain setup details by ID

#### Path Parameters

| Name | Type   | Description                |
| ---- | ------ | -------------------------- |
| id   | string | ID of the sending profile. |

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 " %}

```
{
  "profile_id": "7c82bb2c-ede3-11ea-8215-0a58a9feac2a",
  "profile_name": "default",
  "dns_records": [
    {
      "name": "1h09YTLxhfFx7RivB3QmrH7WaJ9._domainkey.hello.yoursendingdomain.com",
      "type": "CNAME",
      "value": "1h09YTLxhfFx7RivB3QmrH7WaJ9.dkim.smtpd.dev",
      "validation_state": "pending"
    },
    {
      "name": "_amazonses.hello.yoursendingdomain.com",
      "type": "TXT",
      "value": "4ewMcIYic7jCen+qREXsi2j1lBQqT+pVN6WlR6YlMPU=",
      "validation_state": "active"
    },
    {
      "name": "1h09YaQg3pLnAGsb1MHhkZN3RNA._domainkey.hello.yoursendingdomain.com",
      "type": "CNAME",
      "value": "1h09YaQg3pLnAGsb1MHhkZN3RNA.dkim.smtpd.dev",
      "validation_state": "pending"
    },
    {
      "name": "1h09YdNi2ukvX4Vzi9OLYjpaALE._domainkey.hello.yoursendingdomain.com",
      "type": "CNAME",
      "value": "1h09YdNi2ukvX4Vzi9OLYjpaALE.dkim.smtpd.dev",
      "validation_state": "pending"
    },
    {
      "name": "_amazonses.bounce.hello.yoursendingdomain.com",
      "type": "TXT",
      "value": "LcpcfI8N1Tfu1B0+s4gMt2G7/4Ad5vMGjIk64x8hYN8=",
      "validation_state": "active"
    },
    {
      "name": "bounce.hello.yoursendingdomain.com",
      "type": "MX",
      "value": "feedback-smtp.us-east-1.amazonses.com",
      "validation_state": "active"
    },
    {
      "name": "bounce.hello.yoursendingdomain.com",
      "type": "TXT",
      "value": "v=spf1 include:amazonses.com ~all",
      "validation_state": "active"
    },
    {
      "name": "_amazonses.go.yoursendingdomain.com",
      "type": "TXT",
      "value": "C96Xp4B+iPxHNCcQ5xEfMyqOwzI=",
      "validation_state": "pending"
    },
    {
      "name": "go.yoursendingdomain.com",
      "type": "CNAME",
      "value": "l.smtpdgo.com",
      "validation_state": "active"
    }
  ],
  "state": "pending",
  "created_at_utc": 1599137189,
  "modified_at_utc": 1599137191
}
```

{% endtab %}

{% tab title="404 " %}

```
{
  "code": 40401,
  "message": "Resource ID provided is invalid"
}
```

{% endtab %}
{% endtabs %}

## Verify sending profile domain setup

<mark style="color:orange;">`PUT`</mark> `https://api.smtpd.dev/api/v1/profile/email/:id/verify`

This endpoint enqueues a verification task for the sending profile.

#### Path Parameters

| Name | Type   | Description               |
| ---- | ------ | ------------------------- |
| id   | string | ID of the sending profile |

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="202 This request will enqueue a verification task which will update " %}

```
```

{% endtab %}
{% endtabs %}

## Get sending profile by ID

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/profile/email/:id`

This endpoint allows you to get a sending profile by ID.

#### Path Parameters

| Name | Type   | Description                |
| ---- | ------ | -------------------------- |
| id   | string | ID of the sending profile. |

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 " %}
{% tabs %}
{% tab title="" %}

```
{
  "profile_id": "ce26304e-e916-11ea-9063-3af9d3cba4ef",
  "profile_name": "default",
  "sending_domain": "hello.yoursendingdomain.com",
  "link_domain": "go.yoursendingdomain.com",
  "link_domain_default_redirect": "https://google.com",
  "bounce_domain": "bounce.hello.yoursendingdomain.com",
  "state": "active",
  "created_at_utc": 1598609474,
  "modified_at_utc": 1598609476
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="404 " %}

```
{
  "code": 40401,
  "message": "Resource ID provided is invalid"
}
```

{% endtab %}
{% endtabs %}

## Get all sending profiles

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/profile/email`

This endpoint allows you to all the sending profiles for an account.

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 " %}

```
[
  {
    "profile_id": "ce26304e-e916-11ea-9063-3af9d3cba4ef",
    "profile_name": "default",
    "sending_domain": "hello.yoursendingdomain.com",
    "link_domain": "go.yoursendingdomain.com",
    "link_domain_default_redirect": "https://google.com",
    "bounce_domain": "bounce.hello.yoursendingdomain.com",
    "state": "active",
    "created_at_utc": 1598609474,
    "modified_at_utc": 1598609476
  },
  {
    "profile_id": "7c6d545c-edbd-11ea-86ce-3af9d3cba4ef",
    "profile_name": "default",
    "sending_domain": "hello.yoursendingdomain.com",
    "link_domain": "go.yoursendingdomain.com",
    "bounce_domain": "bounce.hello.yoursendingdomain.com",
    "state": "failed",
    "created_at_utc": 1599120868,
    "modified_at_utc": 1599120870
  }
]
```

{% endtab %}
{% endtabs %}


# \[In beta] Email Templates

## Create new email template

<mark style="color:green;">`POST`</mark> `https://api.smtpd.dev/api/v1/email/template`

This endpoint creates a new email template, each template as an associated revision. When you send an email using a template you can default to latest OR a specific revisions, which enables testing for new revisions.&#x20;

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

#### Request Body

| Name                 | Type    | Description                                                            |
| -------------------- | ------- | ---------------------------------------------------------------------- |
| tags                 | object  |                                                                        |
| link\_tracking       | boolean |                                                                        |
| open\_tracking       | boolean |                                                                        |
| reply\_to            | string  |                                                                        |
| from\_name           | string  |                                                                        |
| from\_email\_address | string  |                                                                        |
| content\_text        | string  | The Text email content                                                 |
| content\_html        | string  | The HTML email content                                                 |
| template\_name       | string  | Template name, this will be automatically added as a tag when sending. |

{% tabs %}
{% tab title="201 Template created" %}

```
{
    "template_id": "b9106530-aa81-4776-bf65-ac7d226ae528",
    "revision": 1
}
```

{% endtab %}
{% endtabs %}

## Create new email template revision

<mark style="color:green;">`POST`</mark> `https://api.smtpd.dev/api/v1/email/template/:id`

This endpoint creates a new email template

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

#### Request Body

| Name                 | Type    | Description                                                            |
| -------------------- | ------- | ---------------------------------------------------------------------- |
| tags                 | object  |                                                                        |
| link\_tracking       | boolean |                                                                        |
| open\_tracking       | boolean |                                                                        |
| reply\_to            | string  |                                                                        |
| from\_name           | string  |                                                                        |
| from\_email\_address | string  |                                                                        |
| content\_text        | string  | The Text email content                                                 |
| content\_html        | string  | The HTML email content                                                 |
| template\_name       | string  | Template name, this will be automatically added as a tag when sending. |

{% tabs %}
{% tab title="202 Template created" %}

```
{
    "template_id": "b9106530-aa81-4776-bf65-ac7d226ae528",
    "revision": 2
}
```

{% endtab %}

{% tab title="404 " %}

```
{
  "code": 40401,
  "message": "Resource ID provided is invalid"
}
```

{% endtab %}
{% endtabs %}

## Set revision to $latest

<mark style="color:green;">`POST`</mark> `https://api.smtpd.dev/api/v1/email/template/:id/latest`

This endpoint creates a new email template

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

#### Request Body

| Name     | Type   | Description                     |
| -------- | ------ | ------------------------------- |
| revision | number | The revsion that will be latest |

{% tabs %}
{% tab title="200 Template created" %}

```
null
```

{% endtab %}

{% tab title="404 " %}

```
{
  "code": 40401,
  "message": "Resource ID provided is invalid"
}
```

{% endtab %}
{% endtabs %}


# Forms

These API endpoints support the abaility to add forms for data collection. Each form is attched to a Sending Profile link domain.

## Create new email form

<mark style="color:green;">`POST`</mark> `https://api.smtpd.dev/api/v1/email/form`

This endpoint creates a new email form endpoint.

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

#### Request Body

| Name                                                           | Type    | Description                                    |
| -------------------------------------------------------------- | ------- | ---------------------------------------------- |
| tags                                                           | object  |                                                |
| default\_redirect<mark style="color:red;">\*</mark>            | boolean |                                                |
| success\_redirect<mark style="color:red;">\*</mark>            | boolean |                                                |
| failure\_redirect<mark style="color:red;">\*</mark>            | string  |                                                |
| required\_fields<mark style="color:red;">\*</mark>             | string  |                                                |
| notification\_email\_address<mark style="color:red;">\*</mark> | string  |                                                |
| form\_name<mark style="color:red;">\*</mark>                   | string  | Form name                                      |
| link\_domain<mark style="color:red;">\*</mark>                 | string  | The link domain from an active sending profile |
| enable\_email\_notification                                    | bool    | Enable Notification                            |

{% tabs %}
{% tab title="200: OK Form created" %}

```
{
	"form_id": "9dda916c-086e-40a6-a9d9-2dbe8af76c38",
	"form_key": "2NzhS8VWj1ODBqA3vmwSb4HnbPN",
	"form_name": "Contact Form - NZ",
	"sending_profile_id": "f73d640e-d372-11ed-bdc4-664cfc1c0a60",
	"notification_email_address": "jimmy@yoursendingdomain.com",
	"enable_email_notification": true,
	"notification_email_address_verified": false,
	"form_endpoint": "https://yoursendingdomain.com/f/2NzhS8VWj1ODBqA3vmwSb4HnbPN",
	"default_redirect": "https://www.yoursendingdomain.com",
	"success_redirect": "https://www.yoursendingdomain.com/thank-you",
	"failure_redirect": "https://www.yoursendingdomain.com/contactus/error",
	"required_fields": [
		"email",
		"name"
	],
	"tags": [
		"local"
	],
	"state": "creating",
	"created_at_utc": 1680672814,
	"modified_at_utc": 1680672814
}
```

{% endtab %}
{% endtabs %}

## Get Email Form

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/email/form/:id`

This endpoint allows you to get the form setup details by ID

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="404 " %}

```
{
  "code": 40401,
  "message": "Resource ID provided is invalid"
}
```

{% endtab %}

{% tab title="200: OK " %}

```
{
	"form_id": "7f4be122-5708-4353-afd2-b5a0b6030b16",
	"form_key": "2Nzh9ps32LyFYAkwOO4zh73giSP",
	"form_name": "Contact Us - NZ",
	"sending_profile_id": "f73d640e-d372-11ed-bdc4-664cfc1c0a60",
	"notification_email_address": "jimmy@yoursendingdomain.com",
	"enable_email_notification": true,
	"notification_email_address_verified": false,
	"form_endpoint": "https://yoursendingdomain.com/f/2Nzh9ps32LyFYAkwOO4zh73giSP",
	"default_redirect": "https://www.yoursendingdomain.com",
	"success_redirect": "https://www.yoursendingdomain.com/thank-you",
	"failure_redirect": "https://www.yoursendingdomain.com/contactus/error",
	"required_fields": [
		"email",
		"name"
	],
	"tags": [
		"local"
	],
	"submission_count": 910,
	"state": "disabled",
	"created_at_utc": 1680672669,
	"modified_at_utc": 1680675564
}
```

{% endtab %}
{% endtabs %}

## Disable Email form

<mark style="color:orange;">`PUT`</mark> `https://api.smtpd.dev/api/v1/email/form/:id/disable`

This endpoint disables a form. After a form has been disabled it may take upto 60mins before the endpoint is disabled.

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 Form disabled" %}

```
null
```

{% endtab %}

{% tab title="404 " %}

```
{
  "code": 40401,
  "message": "Resource ID provided is invalid"
}
```

{% endtab %}
{% endtabs %}


# Send

## Send an email

<mark style="color:green;">`POST`</mark> `https://api.smtpd.dev/api/v1/email/send`

This endpoint allows you to send an email where all the content is supplied. The domain from `from_email_address` is used to match a sending profile, If no **active** sending profile is found the email will be rejected.

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

#### Request Body

| Name                      | Type    | Description                                                                                                                                     |
| ------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| content\_text             | string  | The text content for the email body.                                                                                                            |
| content\_html             | string  | The HTML content for the email body.                                                                                                            |
| subject                   | string  | The email subject line.                                                                                                                         |
| from\_name                | string  | The friendly from name                                                                                                                          |
| from\_email\_address      | string  | The from email address, this is used to match the send to an \`active\` sending\_profile.                                                       |
| recipient\_name           | string  | The name of the recipient.                                                                                                                      |
| recipient\_email\_address | string  | The desination email address.                                                                                                                   |
| tags                      | array   | Tags that should be applied to this email for send reporting. You are limited to 256 tags per send with each tag no longer than 256 characters. |
| click\_tracking           | boolean | If [click\_tracking](/user-guide/click-tracking) is enabled.                                                                                    |
| open\_tracking            | boolean | If open tracking is enabled.                                                                                                                    |

{% tabs %}
{% tab title="202 Email send has been successfully enqueued." %}

```
{
  "send_id": "51fa6ce8-e91b-11ea-81e4-0a58a9feac2a",
  "send_key": "1gixrYC2tub7g4O1aYM9qW13sNE",
  "recipient_email_address": "friend@somedomain.com",
  "recipient_name": "Friendship Team",
  "subject": "Welcome From Company Inc",
  "open_tracking": true,
  "click_tracking": true,
  "tags": [
    "hello",
    "me"
  ],
  "state": "accepted",
  "state_category": "accepted",
  "created_at_utc": 1598611413,
  "modified_at_utc": 1598611413
}
```

{% endtab %}

{% tab title="400 When you have no macthing sending profiles in an active state." %}

```
{
  "code": 40020,
  "message": "Sending domain does not exist OR incorectly setup"
}
```

{% endtab %}

{% tab title="401 If the account has not been verified by the SMTPD support team, you will be unable to send any emails and will receive the following error." %}

```
{
  "code": 40901,
  "message": "Account has not been verified"
}
```

{% endtab %}
{% endtabs %}

## Get your last email sends (1000 limit)

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/email/send`

#### Query Parameters

| Name  | Type   | Description                         |
| ----- | ------ | ----------------------------------- |
| limit | number | Limits the number of rows returned. |

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 " %}

```
[
  {
    "send_id": "51fa6ce8-e91b-11ea-81e4-0a58a9feac2a",
    "send_key": "1gixrYC2tub7g4O1aYM9qW13sNE",
    "sending_profile_id": "51fa6ce8-e91b-11ea-81e4-0a58a9feac2a",
    "from_email_address": "hello@yoursendingprofile.com",
    "from_name": "Your Team",
    "recipient_email_address": "friend@somedomain.com",
    "recipient_name": "Friendship Team",
    "subject": "Welcome From Company Inc",
    "open_tracking": true,
    "click_tracking": true,
    "tags": [
      "hello",
      "me"
    ],
    "state": "delivered",
    "state_category": "delivered",
    "created_at_utc": 1598611596,
    "modified_at_utc": 1598611596
  }
]
```

{% endtab %}
{% endtabs %}

## Search sends by recipient email address

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/email/send/search`

#### Query Parameters

| Name | Type   | Description                          |
| ---- | ------ | ------------------------------------ |
| q    | string | Email search term (min 2 characters) |

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 " %}

```
[
  {
    "send_id": "51fa6ce8-e91b-11ea-81e4-0a58a9feac2a",
    "send_key": "1gixrYC2tub7g4O1aYM9qW13sNE",
    "sending_profile_id": "51fa6ce8-e91b-11ea-81e4-0a58a9feac2a",
    "from_email_address": "hello@yoursendingprofile.com",
    "from_name": "Your Team",
    "recipient_email_address": "friend@somedomain.com",
    "recipient_name": "Friendship Team",
    "subject": "Welcome From Company Inc",
    "open_tracking": true,
    "click_tracking": true,
    "tags": [
      "hello",
      "me"
    ],
    "state": "delivered",
    "state_category": "delivered",
    "created_at_utc": 1598611596,
    "modified_at_utc": 1598611596
  }
]
```

{% endtab %}

{% tab title="400 " %}

```
{
  "code": 40005,
  "message": "Resource term not defined or too short"
}
```

{% endtab %}
{% endtabs %}

## Get send by ID

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/email/send/:id`

This endpoint allows you to get the send status details.

#### Path Parameters

| Name | Type   | Description           |
| ---- | ------ | --------------------- |
| id   | string | ID of the email send. |

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 " %}

```
{
  "send_id": "51fa6ce8-e91b-11ea-81e4-0a58a9feac2a",
  "send_key": "1gixrYC2tub7g4O1aYM9qW13sNE",
  "sending_profile_id": "51fa6ce8-e91b-11ea-81e4-0a58a9feac2a",
  "from_email_address": "hello@yoursendingprofile.com",
  "from_name": "Your Team",
  "recipient_email_address": "friend@somedomain.com",
  "recipient_name": "Friendship Team",
  "subject": "Welcome From Company Inc",
  "open_tracking": true,
  "click_tracking": true,
  "tags": [
    "hello",
    "me"
  ],
  "state": "delivered",
  "state_category": "delivered",
  "created_at_utc": 1598611596,
  "modified_at_utc": 1598611596
}
```

{% endtab %}

{% tab title="404 Send ID was not found." %}

```
{
  "code": 40401,
  "message": "Resource ID provided is invalid"
}
```

{% endtab %}
{% endtabs %}

## Get send events by ID

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/email/send/:id/events`

#### Path Parameters

| Name | Type   | Description          |
| ---- | ------ | -------------------- |
| id   | string | ID of the email Send |

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 " %}

```
[
  "send_id": "4eaf17aa-9f5f-11eb-bf67-0a58a9feac02",
  "send_key": "1rI7PS6RycUEBIOy3ig5JDrfX41",
  "sending_profile_id": "4eaf17aa-9f5f-11eb-bf67-0a58a9feac02",
  "from_email_address": "hello@yoursendingdomain.com",
  "from_name": "Your Team",
  "recipient_email_address": "john@smith.com",
  "recipient_name": "John Smith",
  "subject": "Verify your SMTPD - NOW 2021-04-17T19:28:43+10:00",
  "tags": [
    "smtpd.dev/signup",
    "verify"
  ],
  "state": "delivered",
  "events": [
    {
      "id": "0ebe5a9a-3717-45d0-a5ff-3de294362334",
      "metadata": {
          "source": {
            "ip_address": "13.33.17.3"
            "country": "Australia",
            "country_code": "AU"
          },
          "device": {
            "user_agent_family": "Firefox",
            "os_family": "Mac OS X",
            "os_version": "10.15",
            "family": "Mac",
            "brand": "Apple"
          },
          "delivery": {},
          "bounce": {},
          "destination": "https://htmlemail.io"
        },
      "type": "click",
      "created_at_utc": 1600243798
    },
    {
      "id": "0ebe5a9a-3717-45d0-a5ff-3de294362334",
      "metadata": {
          "source": {
            "ip_address": "66.249.84.220"
            "country": "United States",
            "country_code": "US"
          },
          "device": {
            "user_agent_family": "GmailImageProxy",
            "os_family": "Windows",
            "os_version": "XP.",
            "family": "Other"
          },
          "delivery": {},
          "bounce": {},
          "destination": "/o/space.gif"
        },
      "category": "open",
      "created_at_utc": 1600243789
    },
    {
      "id": "0ebe5a9a-3717-45d0-a5ff-3de294362334",
       "metadata": {
          "source": {},
          "device": {},
          "delivery": {
            "mta_raw_response": "250 2.0.0 OK  1648651727 iu16si3379889qvb.40 - gsmtp",
            "mta_ip": "173.194.209.28"
          },
          "bounce": {}
      "category": "delivered",
      "created_at_utc": 1600243789
    },
    {
      "id": "9158ed0a-496e-4a1f-8fcf-12b5268a062c",
      "metadata": {},
      "category": "proccessed",
      "created_at_utc": 1600243789
    },
    {
      "id": "0ebe5a9a-3717-45d0-a5ff-3de294362334",
      "metadata": {
        "source": {
            "ip_address": "66.249.84.220"
            "country": "United States",
            "country_code": "US"
        },
        "device": {
           "raw_user_agent": "curl/1.4.5",
            "user_agent_family": "linux",
            "user_agent_version": "1.4.5",
            "user_agent_major_version": "1",
            "device_family": "Other",
            "device_type": "Unknown"
        },
      },
      "category": "quened",
      "created_at_utc": 1600243789
    }
  ],
  "created_at_utc": 1618651725,
  "modified_at_utc": 1618651727
]
```

{% endtab %}
{% endtabs %}

## Get send HTML content by ID

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/email/send/:id/content/html`

#### Path Parameters

| Name | Type   | Description          |
| ---- | ------ | -------------------- |
| id   | string | ID of the email Send |

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 " %}

```
<HTML>.....</HTML>
```

{% endtab %}
{% endtabs %}

## Get send text content by ID

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/email/send/:id/content/text`

#### Path Parameters

| Name | Type   | Description      |
| ---- | ------ | ---------------- |
| id   | string | ID of email send |

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 " %}

```
text/plain; charset=UTF-8
text Content
```

{% endtab %}
{% endtabs %}


# Analysis

{% hint style="info" %}
These endpoint are only available for customers on the **start-up** and **enterprise** plans. Any period selection is dependent on the plan's defined data retention;

* **Start-up** - 30 day retention period
* **Enterprise** - 2 year retention period
  {% endhint %}

## Get basic account usage for a period

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/analysis/summary?from=2039823098&to=234987234`

<br>

#### Query Parameters

| Name | Type   | Description                                                                                                                                      |
| ---- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| to   | number | <p>Unix Timestamp (epoch) - defaults to the current time<br></p>                                                                                 |
| from | number | <p>Unix Timestamp (epoch) - defaults to current time minus 31 days<br>\* Max range between <code>from</code> and <code>to</code> is 365 days</p> |

#### Headers

| Name                                             | Type   | Description             |
| ------------------------------------------------ | ------ | ----------------------- |
| Authentication<mark style="color:red;">\*</mark> | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 " %}

```
{
 	"group_by": {
		"accepted": {
			"current": 149,
			"previous": 0,
			"delta": 149
		},
		"bounce": {
			"current": 1,
			"previous": 0,
			"delta": 1
		},
		"click": {
			"current": 6,
			"previous": 0,
			"delta": 6
		},
		"delivered": {
			"current": 143,
			"previous": 0,
			"delta": 143
		},
		"open": {
			"current": 9,
			"previous": 0,
			"delta": 9
		},
		"processed": {
			"current": 149,
			"previous": 0,
			"delta": 149
		},
		"queued": {
			"current": 169,
			"previous": 0,
			"delta": 169
		},
		"rejected": {
			"current": 6,
			"previous": 0,
			"delta": 6
		},
		"sent": {
			"current": 149,
			"previous": 0,
			"delta": 149
		}
	},
 	"period": {
   		"from": 1606901470,
    		"to": 1607912472
  	}
}
```

{% endtab %}
{% endtabs %}


# Engagement

## Get deliveries by domain for a period

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/analysis/engagement/delivery/domain/summary?from=1&to=2`

#### Path Parameters

| Name                                             | Type   | Description             |
| ------------------------------------------------ | ------ | ----------------------- |
| Authentication<mark style="color:red;">\*</mark> | string | `Bearer {access_token}` |

#### Query Parameters

| Name | Type   | Description                                                                                                                                                       |
| ---- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| from | number | <p>Unix Timestamp (epoch) in milliseconds - defaults to current time minus 31 days <br>\* Max range between <code>from</code> and <code>to</code> is 365 days</p> |
| to   | number | Unix Timestamp (epoch) in milliseconds - defaults to the current time                                                                                             |

{% tabs %}
{% tab title="200 " %}

```
{
  "total": 1075,
  "group_by": {
    "gmail.com": 669,
    "hotmail.com": 406
  },
  "period": {
    "from": 2039823098,
    "to": 234987234
  }
}
```

{% endtab %}
{% endtabs %}

## Get engagement (Open + Clicks) by country for a period

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/analysis/engagement/country/summary?from=1&to=2`

#### Path Parameters

| Name                                             | Type   | Description             |
| ------------------------------------------------ | ------ | ----------------------- |
| Authentication<mark style="color:red;">\*</mark> | string | `Bearer {access_token}` |

#### Query Parameters

| Name | Type   | Description                                                                                                                                                       |
| ---- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| from | number | <p>Unix Timestamp (epoch)  in milliseconds - defaults to current time minus 31 days<br>\* Max range between <code>from</code> and <code>to</code> is 365 days</p> |
| to   | number | Unix Timestamp (epoch)  in milliseconds - defaults to the current time                                                                                            |

{% tabs %}
{% tab title="200 " %}

```
{
  "total": 1075,
  "group_by": {
    "Australia": 669,
    "United States": 404,
    "unknown": 2
  },
  "period": {
    "from": 2039823098,
    "to": 234987234
  }
}
```

{% endtab %}
{% endtabs %}

## Get engagement (Open + Clicks) by device type for a period

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/analysis/engagement/device/summary?from=1&to=2`

#### Path Parameters

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

#### Query Parameters

| Name | Type   | Description                                                                                                                                                      |
| ---- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| from | number | <p>Unix Timestamp (epoch) in milliseconds - defaults to current time minus 31 days<br>\* Max range between <code>from</code> and <code>to</code> is 365 days</p> |
| to   | number | Unix Timestamp (epoch) in milliseconds - defaults to the current time                                                                                            |

{% tabs %}
{% tab title="200 " %}

```
{
  "total": 1075,
  "group_by": {
    "desktop": 669,
    "mobile": 404,
    "unknown": 2
  },
  "period": {
    "from": 2039823098,
    "to": 234987234
  }
}
```

{% endtab %}
{% endtabs %}


# Delivery

## Get bounce summary for a period

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/analysis/bounce/summary?from=1&to=2`

#### Path Parameters

| Name                                             | Type   | Description             |
| ------------------------------------------------ | ------ | ----------------------- |
| Authentication<mark style="color:red;">\*</mark> | string | `Bearer {access_token}` |

#### Query Parameters

| Name | Type   | Description                                                                                                                                                      |
| ---- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| from | number | <p>Unix Timestamp (epoch) in milliseconds - defaults to current time minus 31 days<br>\* Max range between <code>from</code> and <code>to</code> is 365 days</p> |
| to   | number | Unix Timestamp (epoch) in milliseconds - defaults to the current time                                                                                            |

{% tabs %}
{% tab title="200 " %}

```
{
  "total": 1075,
  "group_by": {
    "gmail.com": 669,
    "hotmail.com": 406
  },
  "period": {
    "from": 2039823098,
    "to": 234987234
  }
}
```

{% endtab %}
{% endtabs %}

## Get bounces by domain for a period

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/analysis/bounce/domain/summary?from=1&to=2`

#### Path Parameters

| Name                                             | Type   | Description             |
| ------------------------------------------------ | ------ | ----------------------- |
| Authentication<mark style="color:red;">\*</mark> | string | `Bearer {access_token}` |

#### Query Parameters

| Name | Type   | Description                                                                                                                                                      |
| ---- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| from | number | <p>Unix Timestamp (epoch) in milliseconds - defaults to current time minus 31 days<br>\* Max range between <code>from</code> and <code>to</code> is 365 days</p> |
| to   | number | Unix Timestamp (epoch) in milliseconds - defaults to the current time                                                                                            |

{% tabs %}
{% tab title="200 " %}

```
{
  "total": 1075,
  "group_by": {
    "gmail.com": 669,
    "hotmail.com": 406
  },
  "period": {
    "from": 2039823098,
    "to": 234987234
  }
}
```

{% endtab %}
{% endtabs %}


# Account & Billing

## Get account details

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/account`

This endpoint allows you to get the account details of the currently logged in user.

#### Headers

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 " %}

```
{
  "id": "811affc1-66c7-4982-b39e-29f9536b4720",
  "account_name": "James Hardie Industries Inc",
  "user_count": 1,
  "api_key_count": 0,
  "billing_contact_email_address": "jack.truong@jameshardie.com",
  "plan_id": "dbef0751-42b7-424e-8d1f-4ad67c478a2d",
  "is_verified": true,
  "created_at_utc": 1598610725,
  "modified_at_utc": 1598610963
}
```

{% endtab %}
{% endtabs %}


# Users

## Get account users

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/account/user`

#### Path Parameters

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 " %}

```
[
  {
    "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": 1598610725,
    "modified_at_utc": 1598610725
  }
]
```

{% endtab %}
{% endtabs %}


# API Keys

## Generate new API Key

<mark style="color:green;">`POST`</mark> `https://api.smtpd.dev/api/v1/account/api_key`

**IMPORTANT**: The generated secret will be visible only once. After the key has been created, you will only be able to see the name of the key.

{% hint style="warning" %}
API Keys are automatically revoked after 90 days of inactivity.
{% endhint %}

#### Path Parameters

| Name                                             | Type   | Description             |
| ------------------------------------------------ | ------ | ----------------------- |
| Authentication<mark style="color:red;">\*</mark> | string | `Bearer {access_token}` |

#### Request Body

| Name                                   | Type   | Description                                                                                                                                                               |
| -------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| role<mark style="color:red;">\*</mark> | string | <p>The permission role for the API key. Supports the following roles;</p><p><code>iac</code>, <code>standard</code>, <code>read\_only</code>, <code>send\_only</code></p> |
| name<mark style="color:red;">\*</mark> | string | Name for API key                                                                                                                                                          |

{% tabs %}
{% tab title="201 " %}

```
{
  "ID": "ad75ae9c-f133-11eb-ab65-0a58a9feaca0",
  "Name": "PROD - Datadog",
  "Key": "ty5davhlalixzn7+2+4l9yemuxdprs8m2ue45vtxsot/zjngii1ptlrzxleceojvxos423om1zsu0apx6wmira==/1w2fsrgv7mayczileqw5svnduj3",
  "Secret": "lloIT4+/3636UvGI2dTm20DH/V9cdFpzHNcET142I32sKVmZV95xnYkVD7CZT7XhoHnQmYS7n/EE7DQmZMv7eoa+k+E/HVXXbjqmB3OFMccSJxboO17wiokvZGgr7Hsdw3LAwrWeYtdAHwzpFB/73JCg7mJ5Ln5ntzfKB1v10dY=/1w2FsQmMFMtP4h1x8lMjhoEwYv8"
}
```

{% endtab %}
{% endtabs %}

## Get all API Keys

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/account/api_key`

#### Path Parameters

| Name                                             | Type   | Description             |
| ------------------------------------------------ | ------ | ----------------------- |
| Authentication<mark style="color:red;">\*</mark> | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 " %}

```
[
  {
    "id": "055e24ae-f132-11eb-a5ac-0a58a9feac2b",
    "account_id": "35132685-7dcf-4b2a-8c88-88ccf4848925",
    "name": "Staging - AWS",
    "key": "oqzedt51ibrwg5u2tgoanah1eulilowfj3+hcjlydywquze647c8jvyrqvx5ykeivttzo3ulxaa2a3/gecc08w==/1w2eqx3nkawstmkzct7zk7c5uyw",
    "is_active": true,
    "last_accessed_at_utc": 1827618270,
    "created_at_utc": 1627618270,
    "modified_at_utc": 1627618270
  },
  {
    "id": "ad75aea0-f133-11eb-ab65-0a58a9feaca0",
    "account_id": "35132685-7dcf-4b2a-8c88-88ccf4848925",
    "name": "PROD - Datadog",
    "key": "ty5davhlalixzn7+2+4l9yemuxdprs8m2ue45vtxsot/zjngii1ptlrzxleceojvxos423om1zsu0apx6wmira==/1w2fsrgv7mayczileqw5svnduj3",
    "is_active": true,
    "last_accessed_at_utc": 1827618270,
    "created_at_utc": 1627642982,
    "modified_at_utc": 1627642982
  }
]
```

{% endtab %}
{% endtabs %}

## Get an API Key by ID

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/account/api_key/:id`

#### Headers

| Name                                             | Type   | Description             |
| ------------------------------------------------ | ------ | ----------------------- |
| Authentication<mark style="color:red;">\*</mark> | String | `Bearer {access_token}` |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "id": "055e24ae-f132-11eb-a5ac-0a58a9feec2b",
    "account_id": "35132685-7dcf-4b2a-8c88-88ccf4848925",
    "name": "Staging - AWS",
    "key": "oqzedt51ibrwg5u2tgoanah1eulilowfj3+hcjlydywquze647c8jvyrqvx5ykeivttzo3ulxaa2a3/gecc08w==/1w2eqx3nkawstmkzct7zk7c5uyw",
    "is_active": true,
    "last_accessed_at_utc": 1827618270,
    "created_at_utc": 1627618270,
    "modified_at_utc": 1627618270
  }
```

{% endtab %}
{% endtabs %}

## Get API Key sessions by ID

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/account/api_key/:id/sessions`

#### Headers

| Name                                             | Type   | Description             |
| ------------------------------------------------ | ------ | ----------------------- |
| Authentication<mark style="color:red;">\*</mark> | String | `Bearer {access_token}` |

{% tabs %}
{% tab title="200: OK " %}

```javascript
[
	{
		"id": "3430b8f0-b04b-48c9-824e-dae631f3ecd8",
		"account_id": "34132685-7dcf-4b2a-8c88-48ccff847925",
		"ip_address": "22.2.3.28",
		"raw_user_agent": "",
		"user_agent_family": "",
		"user_agent_version": "",
		"user_agent_major_version": "",
		"os_family": "",
		"os_version": "",
		"device_family": "Other",
		"device_brand": "",
		"device_type": "Unknown",
		"country": "United States",
		"country_iso_code": "US",
		"is_active": true,
		"created_at_utc": 1657870731,
		"modified_at_utc": 1657870731
	}
]
```

{% endtab %}
{% endtabs %}

## Revoke an API key

<mark style="color:orange;">`PUT`</mark> `https://api.smtpd.dev/api/v1/account/api_key/:id/revoke`

#### Path Parameters

| Name                                             | Type   | Description             |
| ------------------------------------------------ | ------ | ----------------------- |
| Authentication<mark style="color:red;">\*</mark> | string | `Bearer {access_token}` |
| id<mark style="color:red;">\*</mark>             | string | API Key ID              |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}


# Roles & Permissions

When account is created a number of system Roles are created to support various permission needs.

<table><thead><tr><th width="138">Role</th><th width="135">API Name</th><th width="473"></th></tr></thead><tbody><tr><td>Owner</td><td><code>owner</code></td><td>This role has complete access to the account, default role assigned to the signup user.</td></tr><tr><td>Admin</td><td><code>admin</code></td><td>This role has complete access except changing the <code>owner</code> role.</td></tr><tr><td>IaC</td><td><code>iac</code></td><td>This role has access to creating resources on the platform including;<br>* Sending Profiles<br>* Web Forms<br>* Templates<br>This role does not have <strong>sending</strong> permission.</td></tr><tr><td>Standard</td><td><code>standard</code></td><td>This role has <em>read-only</em> access &#x26; <strong>sending</strong> permission.</td></tr><tr><td>ReadOnly</td><td><code>read_only</code></td><td>This role has <em>read-only</em> access to all resources.</td></tr><tr><td>SendOnly</td><td><code>send_only</code></td><td>This role only has <strong>sending</strong> permission.</td></tr></tbody></table>


# Billing & Usage

## Get current account billing plan

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/account/billing/plan/current`

#### Path Parameters

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 " %}

```
{
  "plan_id": "dbef0751-42b7-424e-8d1f-4ad67c478a2d",
  "plan_name": "Free - Forever!",
  "price_usd_per_month": "0.00",
  "max_emails_per_month": 5000,
  "enforce_plan_limit": true,
  "extra_thousand_emails_cost": "",
  "max_sending_profiles": 1,
  "max_retention_days": 7,
  "feature_email_validation": false,
  "feature_basic_reporting": false,
  "feature_advance_reporting": false
}
```

{% endtab %}
{% endtabs %}

## Get account usage (Last 30 days)

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/account/billing/usage`

#### Path Parameters

| Name           | Type   | Description             |
| -------------- | ------ | ----------------------- |
| Authentication | string | `Bearer {access_token}` |

{% tabs %}
{% tab title="200 " %}

```
{
  "total": 4087,
  "total_by_category": {
    "unknown": 40,
    "accepted": 6,
    "proccessed": 0,
    "sent": 2,
    "delivered":4003,
    "bounced": 1,
    "complaint": 0,
    "rejected": 35,
  }
```

{% endtab %}
{% endtabs %}

## Get available billing plans

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/billing/plan`

This endpoint returns all current billing plans for SMTPD, along with their limits and features

{% tabs %}
{% tab title="200: OK " %}

```json
[
  {
    "plan_id": "dbef0751-42b7-424e-8d1f-4ad67c478a2d",
    "name": "free",
    "description": "Free - Forever! Gives you 5k free emails to send every month, perfect for developer projects OR testing",
    "price_usd_per_month": "0.00",
    "max_emails_per_month": 5000,
    "enforce_plan_limit": true,
    "extra_thousand_emails_cost": "",
    "max_sending_profiles": 1,
    "max_retention_days": 7,
    "feature_email_validation": false,
    "feature_basic_reporting": false,
    "feature_advance_reporting": false
  },
  {
    "plan_id": "10e5dba8-903d-4623-afc6-0d4a17852931",
    "name": "startup",
    "description": "Startup - Gives you 200k emails every month, perfect for small to medium projects",
    "price_usd_per_month": "90.00",
    "max_emails_per_month": 200000,
    "enforce_plan_limit": false,
    "extra_thousand_emails_cost": "0.80",
    "max_sending_profiles": 2,
    "max_retention_days": 30,
    "feature_email_validation": true,
    "feature_basic_reporting": true,
    "feature_advance_reporting": false
  },
  {
    "plan_id": "0cd5639c-c493-4d84-a95a-716ffb7fdabb",
    "name": "enterprise",
    "description": "Enterprise - Gives you 1 million emails every month & advanced reporting, perfect for medium to large projects",
    "price_usd_per_month": "450.00",
    "max_emails_per_month": 1000000,
    "enforce_plan_limit": false,
    "extra_thousand_emails_cost": "0.60",
    "max_sending_profiles": 10,
    "max_retention_days": 730,
    "feature_email_validation": true,
    "feature_basic_reporting": true,
    "feature_advance_reporting": true
  }]json
```

{% endtab %}
{% endtabs %}

## Get billing plan by ID

<mark style="color:blue;">`GET`</mark> `https://api.smtpd.dev/api/v1/billing/plan/:id`

This endpoint returns a billing plan by ID

{% tabs %}
{% tab title="200 " %}

```json
{
    "plan_id": "dbef0751-42b7-424e-8d1f-4ad67c478a2d",
    "name": "free",
    "description": "Free - Forever! Gives you 5k free emails to send every month, perfect for developer projects OR testing",
    "price_usd_per_month": "0.00",
    "max_emails_per_month": 5000,
    "enforce_plan_limit": true,
    "extra_thousand_emails_cost": "",
    "max_sending_profiles": 1,
    "max_retention_days": 7,
    "feature_email_validation": false,
    "feature_basic_reporting": false,
    "feature_advance_reporting": false
 }
```

{% endtab %}
{% endtabs %}