API Reference

Emails

Send transactional or one-off emails and check their delivery status.

Send an Email

POST

/emails

Queues an email for immediate sending. If the recipient does not exist as a contact, one is automatically created.

Body

from

string

Sender email address. Must be a verified sending email in your account.

Required

to

string

Recipient email address.

Required

subject

string

Email subject line. Max 255 characters.

Required

html

string

HTML body. Required if `text` is not provided.

Optional

text

string

Plain text body. Required if `html` is not provided.

Optional

reply_to

string

Reply-to email address.

Optional

tags

array

Array of string tags for categorization.

Optional

headers

object

Custom email headers as key-value pairs.

Optional

Example

curl -X POST https://mailtani.com/api/v1/emails \
  -H "Authorization: Bearer mk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Your invoice is ready",
    "html": "<h1>Invoice #1234</h1><p>Your invoice is attached.</p>",
    "text": "Invoice #1234 - Your invoice is attached.",
    "reply_to": "[email protected]",
    "tags": ["invoice", "billing"]
  }'

Response 202 Accepted

{
  "data": {
    "id": 42,
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Your invoice is ready",
    "status": "queued",
    "provider": "ses",
    "tags": ["invoice", "billing"],
    "created_at": "2026-01-15T10:30:00+00:00",
    "sent_at": null,
    "delivered_at": null,
    "opened_at": null,
    "bounced_at": null
  }
}

Get Email Status

GET

/emails/{id}

Retrieve the current status and delivery details of a sent email.

Example

curl https://mailtani.com/api/v1/emails/42 \
  -H "Authorization: Bearer mk_your_api_key_here"

Response 200 OK

{
  "data": {
    "id": 42,
    "from": "[email protected]",
    "to": "[email protected]",
    "subject": "Your invoice is ready",
    "status": "delivered",
    "provider": "ses",
    "tags": ["invoice", "billing"],
    "created_at": "2026-01-15T10:30:00+00:00",
    "sent_at": "2026-01-15T10:30:02+00:00",
    "delivered_at": "2026-01-15T10:30:05+00:00",
    "opened_at": null,
    "bounced_at": null
  }
}

Email Statuses

Status	Description
`queued`	Email is queued for sending
`sent`	Email has been sent to the provider
`delivered`	Email was delivered to the recipient
`bounced`	Email bounced (hard or soft bounce)