Create Conversational Message

curl --request POST \
  --url https://api.ahasend.com/v2/accounts/{account_id}/messages/conversation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": {
    "email": "[email protected]",
    "name": "Example Corp"
  },
  "to": [
    {
      "email": "[email protected]",
      "name": "John Doe"
    },
    {
      "email": "[email protected]",
      "name": "Jane Doe"
    }
  ],
  "cc": [
    {
      "email": "[email protected]",
      "name": "Example Corp HR"
    }
  ],
  "bcc": [
    {
      "email": "[email protected]",
      "name": "BCC Recipient"
    }
  ],
  "subject": "Welcome to Example Corp",
  "html_content": "<h1>Dear John and Jane, welcome to Example Corp!</h1>",
  "text_content": "Dear John and Jane, welcome to Example Corp!"
}
'

{
  "object": "list",
  "data": [
    {
      "object": "message",
      "recipient": {
        "email": "[email protected]",
        "name": "John Doe",
        "substitutions": {
          "first_name": "John",
          "order_id": "12345"
        }
      },
      "status": "queued",
      "id": "<[email protected]>",
      "error": "<string>",
      "schedule": {
        "first_attempt": "2023-12-25T10:30:00Z",
        "expires": "2023-12-26T10:30:00Z"
      }
    }
  ]
}

Messages

Create Conversational Message

Creates and sends a conversational message (with support for CC and BCC) to one or more recipients. This API does not support template substitutions, use Create Message instead if you need substitutions.

Validation Requirements:

Either text_content or html_content is required
from.email must be from a domain you own with valid DNS records
retention.metadata must be between 1 and 30 days
retention.data must be between 0 and 30 days
If the reply_to parameter is provided, do not include reply-to in headers
If the cc parameter is provided, do not include cc in headers
message-id header will be ignored and automatically generated
Schedule times must be in RFC3339 format

POST

accounts

{account_id}

messages

conversation

Create Conversational Message

curl --request POST \
  --url https://api.ahasend.com/v2/accounts/{account_id}/messages/conversation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "from": {
    "email": "[email protected]",
    "name": "Example Corp"
  },
  "to": [
    {
      "email": "[email protected]",
      "name": "John Doe"
    },
    {
      "email": "[email protected]",
      "name": "Jane Doe"
    }
  ],
  "cc": [
    {
      "email": "[email protected]",
      "name": "Example Corp HR"
    }
  ],
  "bcc": [
    {
      "email": "[email protected]",
      "name": "BCC Recipient"
    }
  ],
  "subject": "Welcome to Example Corp",
  "html_content": "<h1>Dear John and Jane, welcome to Example Corp!</h1>",
  "text_content": "Dear John and Jane, welcome to Example Corp!"
}
'

{
  "object": "list",
  "data": [
    {
      "object": "message",
      "recipient": {
        "email": "[email protected]",
        "name": "John Doe",
        "substitutions": {
          "first_name": "John",
          "order_id": "12345"
        }
      },
      "status": "queued",
      "id": "<[email protected]>",
      "error": "<string>",
      "schedule": {
        "first_attempt": "2023-12-25T10:30:00Z",
        "expires": "2023-12-26T10:30:00Z"
      }
    }
  ]
}

Authorizations

Authorization

string

header

required

API key for authentication

Headers

Idempotency-Key

string

Optional idempotency key for safe request retries. Must be a unique string for each logical request. Requests with the same key will return the same response. Keys expire after 24 hours.

Maximum string length: 255

Path Parameters

account_id

string<uuid>

required

Account ID

Body

application/json

from

object

required

Show child attributes

from.email

string<email>

required

Valid email address from a domain defined in your account with valid DNS records

from.name

string

Display name for the sender

Example:

{
  "email": "[email protected]",
  "name": "Example Corp"
}

subject

string

required

Email subject line

object[]

This parameter can set the To header to multiple addresses.

Minimum array length: 1

Show child attributes

to.email

string<email>

required

Valid email address from a domain defined in your account with valid DNS records

to.name

string

Display name for the sender

object[]

This parameter can set the CC header to multiple addresses. Do not include cc in the headers array.

Minimum array length: 1

Show child attributes

cc.email

string<email>

required

Valid email address from a domain defined in your account with valid DNS records

cc.name

string

Display name for the sender

bcc

object[]

This parameter can set the To header to multiple addresses.

Minimum array length: 1

Show child attributes

bcc.email

string<email>

required

Valid email address from a domain defined in your account with valid DNS records

bcc.name

string

Display name for the sender

reply_to

object

If provided, the reply-to header in headers array must not be provided

Show child attributes

reply_to.email

string<email>

required

Valid email address from a domain defined in your account with valid DNS records

reply_to.name

string

Display name for the sender

Example:

{
  "email": "[email protected]",
  "name": "Example Corp"
}

text_content

string

Plain text content. Required if html_content is empty

html_content

string

HTML content. Required if text_content is empty

amp_content

string

AMP HTML content

attachments

object[]

File attachments

Show child attributes

attachments.data

string

required

Either plaintext or base64 encoded attachment data (depending on base64 field)

attachments.content_type

string

required

The MIME type of the attachment

attachments.file_name

string

required

The filename of the attachment

attachments.base64

boolean

default:false

If true, data must be encoded using base64. Otherwise, data will be interpreted as UTF-8

attachments.content_disposition

string

The disposition of the attachment

attachments.content_id

string

The Content-ID of the attachment for inline images

headers

object

Custom email headers. cc and reply-to headers cannot be provided if reply_to or cc parameters are provided, message-id will be ignored and automatically generated

Show child attributes

headers.{key}

string

Response

Message created successfully

object

enum<string>

required

Object type identifier

Available options:

list

data

object[]

required

List of messages and their statuses

Show child attributes

data.object

enum<string>

required

Object type identifier

Available options:

message

data.recipient

object

required

Show child attributes

data.recipient.email

string<email>

required

Recipient email address

data.recipient.name

string

Display name for the recipient

data.recipient.substitutions

object

Substitution data for the recipient. Used with jinja2 templating language for dynamic content

Example:

{
  "email": "[email protected]",
  "name": "John Doe",
  "substitutions": { "first_name": "John", "order_id": "12345" }
}

data.status

enum<string>

required

Status of the message

Available options:

queued,

scheduled,

error

data.id

string | null

Message ID (null if the message was not sent)

Example:

"<[email protected]>"

data.error

string | null

Error message if the message was not sent

data.schedule

object

Provided if the request contained a schedule

Show child attributes

data.schedule.first_attempt

string<date-time>

The time to make the first attempt for delivering the message (RFC3339 format)

data.schedule.expires

string<date-time>

Expire and drop the message if not delivered by this time (RFC3339 format)

Example:

{
  "first_attempt": "2023-12-25T10:30:00Z",
  "expires": "2023-12-26T10:30:00Z"
}

Create Message Get Message

⌘I

Overview

API reference

Webhooks

Message Routing

API v1 (legacy)

Create Conversational Message

Authorizations

Headers

Path Parameters

Body

Response