Emails

Send, retrieve, and manage individual emails through the Txtly API.

Send Email

POST

/v1/emails

Send a single email message. Returns the email object with a unique ID.

Parameters

Parameter	Type	Description
`from`required	`string`	Sender email address
`to`required	`string[]`	Array of recipient email addresses
`subject`required	`string`	Email subject line
`html`	`string`	HTML email body
`text`	`string`	Plain text email body
`cc`	`string[]`	Carbon copy recipients
`bcc`	`string[]`	Blind carbon copy recipients
`replyTo`	`string`	Reply-to email address
`scheduledAt`	`string (ISO 8601)`	Schedule email for future delivery
`headers`	`object`	Custom email headers as key-value pairs
`tags`	`object`	Key-value pairs for organization and tracking
`templateId`	`string`	ID of a published template to use for the email body
`templateVariables`	`object`	Key-value pairs to interpolate into the template (e.g. {"first_name": "Alice"})
`attachments`	`object[]`	Array of file attachments. Each requires filename and base64-encoded content

Example Request

curl -X POST https://api.txtly.com.au/v1/emails \
  -H "Authorization: Bearer tx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "noreply@example.com",
    "to": ["user@example.com"],
    "subject": "Welcome to Txtly",
    "html": "<h1>Hello</h1><p>Welcome aboard!</p>",
    "text": "Hello. Welcome aboard!",
    "tags": {"signup": "true"}
  }'

Example Response

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "from": "noreply@example.com",
  "to": ["user@example.com"],
  "cc": null,
  "bcc": null,
  "subject": "Welcome to Txtly",
  "html": "<h1>Hello</h1><p>Welcome aboard!</p>",
  "text": "Hello. Welcome aboard!",
  "status": "queued",
  "scheduledAt": null,
  "createdAt": "2026-03-21T10:30:00Z"
}

Send Batch Emails

POST

/v1/emails/batch

Send up to 100 emails in a single request for improved performance.

Parameters

Parameter	Type	Description
`emails`required	`object[]`	Array of email objects with same parameters as single email endpoint (max 100)

Example Request

curl -X POST https://api.txtly.com.au/v1/emails/batch \
  -H "Authorization: Bearer tx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "emails": [
      {
        "from": "noreply@example.com",
        "to": ["user1@example.com"],
        "subject": "Hello User 1",
        "html": "<p>Welcome</p>"
      },
      {
        "from": "noreply@example.com",
        "to": ["user2@example.com"],
        "subject": "Hello User 2",
        "html": "<p>Welcome</p>"
      }
    ]
  }'

Example Response

{
  "data": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "from": "noreply@example.com",
      "to": ["user1@example.com"],
      "cc": null,
      "bcc": null,
      "subject": "Hello User 1",
      "html": "<p>Welcome</p>",
      "text": null,
      "status": "queued",
      "scheduledAt": null,
      "createdAt": "2026-03-21T10:30:00Z"
    },
    {
      "id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
      "from": "noreply@example.com",
      "to": ["user2@example.com"],
      "cc": null,
      "bcc": null,
      "subject": "Hello User 2",
      "html": "<p>Welcome</p>",
      "text": null,
      "status": "queued",
      "scheduledAt": null,
      "createdAt": "2026-03-21T10:30:00Z"
    }
  ]
}

List Emails

GET

/v1/emails

List sent emails with cursor-based pagination.

Query Parameters

Parameter	Type	Description
`limit`	`number`	Results per page (default: 20, max: 100)
`cursor`	`string`	Cursor for pagination (from previous response)

Example Response

{
  "data": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "from": "noreply@example.com",
      "to": ["user@example.com"],
      "subject": "Welcome to Txtly",
      "status": "delivered",
      "domainName": "example.com",
      "sentAt": "2026-03-21T10:30:05Z",
      "createdAt": "2026-03-21T10:30:00Z"
    }
  ],
  "cursor": "eyJpZCI6Imxhc3RfaWQifQ==",
  "hasMore": true
}

Get Email

GET

/v1/emails/{id}

Retrieve an email by ID.

Path Parameters

Parameter	Type	Description
`id`required	`string`	Email ID

Example Response

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "from": "noreply@example.com",
  "to": ["user@example.com"],
  "cc": null,
  "bcc": null,
  "subject": "Welcome to Txtly",
  "html": "<h1>Hello</h1><p>Welcome aboard!</p>",
  "text": "Hello. Welcome aboard!",
  "status": "delivered",
  "scheduledAt": null,
  "createdAt": "2026-03-21T10:30:00Z"
}

Get Email Events

GET

/v1/emails/{id}/events

Retrieve all lifecycle events for a specific email.

Path Parameters

Parameter	Type	Description
`id`required	`string`	Email ID

Example Response

{
  "data": [
    {
      "id": "e1f2a3b4-5678-90ab-cdef-1234567890ab",
      "type": "sent",
      "createdAt": "2026-03-21T10:30:05Z"
    },
    {
      "id": "f2a3b4c5-6789-01bc-def0-2345678901bc",
      "type": "delivered",
      "createdAt": "2026-03-21T10:30:15Z"
    }
  ]
}

Cancel Email

POST

/v1/emails/{id}/cancel

Cancel a scheduled email before it is sent. Only emails with status 'scheduled' can be cancelled.

Path Parameters

Parameter	Type	Description
`id`required	`string`	Email ID

Example Request

curl -X POST https://api.txtly.com.au/v1/emails/d290f1ee-.../cancel \
  -H "Authorization: Bearer tx_your_api_key"

Example Response

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "from": "noreply@example.com",
  "to": ["user@example.com"],
  "cc": null,
  "bcc": null,
  "subject": "Welcome to Txtly",
  "html": "<h1>Hello</h1>",
  "text": null,
  "status": "cancelled",
  "scheduledAt": "2026-04-01T09:00:00Z",
  "createdAt": "2026-03-21T10:30:00Z"
}

Reschedule Email

PATCH

/v1/emails/{id}

Update the scheduled send time of a scheduled email.

Parameters

Parameter	Type	Description
`scheduledAt`required	`string (ISO 8601)`	New scheduled send time (must be in the future)

Example Request

curl -X PATCH https://api.txtly.com.au/v1/emails/d290f1ee-... \
  -H "Authorization: Bearer tx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"scheduledAt": "2026-04-02T09:00:00Z"}'

Example Response

{
  "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "from": "noreply@example.com",
  "to": ["user@example.com"],
  "cc": null,
  "bcc": null,
  "subject": "Welcome to Txtly",
  "html": "<h1>Hello</h1>",
  "text": null,
  "status": "scheduled",
  "scheduledAt": "2026-04-02T09:00:00Z",
  "createdAt": "2026-03-21T10:30:00Z"
}

Email Events

Emails generate events throughout their lifecycle. You can listen to these events via webhooks or retrieve them with the Get Email Events endpoint.

Event Types

email.sentEmail was accepted by the mail server
email.deliveredEmail was successfully delivered to recipient
email.delivery_delayedDelivery was delayed but will be retried
email.bouncedEmail bounced at recipient server
email.complainedRecipient marked email as spam
email.openedRecipient opened the email
email.clickedRecipient clicked a link in the email