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

ParameterTypeDescription
fromrequiredstringSender email address
torequiredstring[]Array of recipient email addresses
subjectrequiredstringEmail subject line
htmlstringHTML email body
textstringPlain text email body
ccstring[]Carbon copy recipients
bccstring[]Blind carbon copy recipients
reply_tostringReply-to email address
template_idstringTemplate ID to use for rendering
template_variablesobjectVariables for template substitution
scheduled_atstring (ISO 8601)Schedule email for future delivery
headersobjectCustom email headers
tagsobject[]Tags for organization and tracking
attachmentsobject[]Email attachments with filename and content

Example Request

curl -X POST https://api.txtly.io/v1/emails \
  -H "Authorization: Bearer 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": [{"name": "signup", "value": "true"}]
  }'

Example Response

{
  "id": "email_abc123xyz789",
  "from": "noreply@example.com",
  "to": ["user@example.com"],
  "subject": "Welcome to Txtly",
  "status": "queued",
  "created_at": "2026-03-21T10:30:00Z",
  "scheduled_at": null,
  "events": []
}

Send Batch Emails

POST
/v1/emails/batch

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

Parameters

Array of email objects with same parameters as single email endpoint (max 100).

Example Request

curl -X POST https://api.txtly.io/v1/emails/batch \
  -H "Authorization: Bearer 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

{
  "batch_id": "batch_def456ghi789",
  "emails": [
    {
      "id": "email_abc123xyz789",
      "to": ["user1@example.com"],
      "status": "queued"
    },
    {
      "id": "email_def456uvw789",
      "to": ["user2@example.com"],
      "status": "queued"
    }
  ],
  "created_at": "2026-03-21T10:30:00Z"
}

Get Email

GET
/v1/emails/{id}

Retrieve an email by ID including all associated events.

Path Parameters

ParameterTypeDescription
idrequiredstringEmail ID

Example Response

{
  "id": "email_abc123xyz789",
  "from": "noreply@example.com",
  "to": ["user@example.com"],
  "subject": "Welcome to Txtly",
  "status": "delivered",
  "created_at": "2026-03-21T10:30:00Z",
  "events": [
    {
      "type": "email.sent",
      "timestamp": "2026-03-21T10:30:05Z"
    },
    {
      "type": "email.delivered",
      "timestamp": "2026-03-21T10:30:15Z"
    },
    {
      "type": "email.opened",
      "timestamp": "2026-03-21T10:35:22Z"
    }
  ]
}

Cancel Scheduled Email

PATCH
/v1/emails/{id}

Cancel a scheduled email that hasn't been sent yet.

Parameters

ParameterTypeDescription
statusstringSet to "cancelled" to cancel the email

Example Request

curl -X PATCH https://api.txtly.io/v1/emails/email_abc123xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "cancelled"
  }'

Email Events

Emails generate events throughout their lifecycle. You can listen to these events via webhooks or retrieve them with the Get Email 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