# 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.md) 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.smtpd.dev/api/send.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.