API Reference

Campaigns

Create and manage email campaigns. Campaigns can be broadcast (one-time send) or sequence (multi-step drip).

List Campaigns

GET

/campaigns

Returns all campaigns in the current project.

Example

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

Response 200 OK

{
  "data": [
    {
      "id": 1,
      "name": "Welcome Series",
      "type": "sequence",
      "status": "draft",
      "timezone": "UTC",
      "scheduled_at": null,
      "enrollments_count": 0,
      "steps": [
        {
          "id": 1,
          "step_order": 1,
          "subject": "Welcome to Mailtani!",
          "body": "<p>Thanks for signing up...</p>",
          "delay_days": 0
        }
      ],
      "created_at": "2026-01-10T08:00:00+00:00",
      "updated_at": "2026-01-10T08:00:00+00:00"
    }
  ]
}

Create a Campaign

POST

/campaigns

Body

name

string

Campaign name.

Required

type

string

`broadcast` for a one-time send, or `sequence` for a multi-step drip.

Required

timezone

string

default: UTC

Timezone for scheduling (e.g. `America/New_York`).

Optional

scheduled_at

string

ISO 8601 datetime for a scheduled broadcast send.

Optional

steps

array

Array of campaign steps. Each step requires `subject`, `body`, and `delay_days`.

Required

steps[].subject

string

Email subject for this step.

Required

steps[].body

string

HTML email body for this step.

Required

steps[].delay_days

integer

Days to wait before sending this step. Use `0` for immediate.

Required

Example

curl -X POST https://mailtani.com/api/v1/campaigns \
  -H "Authorization: Bearer mk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Welcome Series",
    "type": "sequence",
    "timezone": "America/New_York",
    "steps": [
      {
        "subject": "Welcome!",
        "body": "<p>Thanks for joining.</p>",
        "delay_days": 0
      },
      {
        "subject": "Getting started",
        "body": "<p>Here are some tips...</p>",
        "delay_days": 3
      }
    ]
  }'

Response 201 Created — returns the created campaign object.

Get a Campaign

GET

/campaigns/{id}

Returns full campaign details including steps and enrollment count.

Example

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

Response 200 OK — returns the campaign object.

Update a Campaign

PUT

/campaigns/{id}

Only draft campaigns can be updated. Attempting to update an active or completed campaign returns a 422 error.

Accepts the same body as Create. If steps is provided, existing steps are replaced entirely.

Example

curl -X PUT https://mailtani.com/api/v1/campaigns/1 \
  -H "Authorization: Bearer mk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Welcome Series v2" }'

Response 200 OK — returns the updated campaign object.

Delete a Campaign

DELETE

/campaigns/{id}

Only draft campaigns can be deleted.

Example

curl -X DELETE https://mailtani.com/api/v1/campaigns/1 \
  -H "Authorization: Bearer mk_your_api_key_here"

Response 204 No Content

Activate a Campaign

POST

/campaigns/{id}/activate

Transitions a draft campaign to active status. The campaign must have at least one enrollment.

Example

curl -X POST https://mailtani.com/api/v1/campaigns/1/activate \
  -H "Authorization: Bearer mk_your_api_key_here"

Response 200 OK

Error responses

Code	Condition
`campaign_not_draft`	Campaign is not in draft status
`no_enrollments`	Campaign has no enrolled contacts

Enroll Contacts

POST

/campaigns/{id}/enroll

Enroll specific contacts into a campaign. Already-enrolled and non-mailable contacts are skipped.

Body

contact_ids

array

Array of contact IDs to enroll.

Required

Example

curl -X POST https://mailtani.com/api/v1/campaigns/1/enroll \
  -H "Authorization: Bearer mk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "contact_ids": [1, 2, 3, 4, 5] }'

Response 200 OK

{ "enrolled": 4, "skipped": 1 }

Enroll Segment

POST

/campaigns/{id}/enroll-segment

Enroll all contacts matching a segment's conditions into the campaign.

Body

segment_id

integer

The ID of the segment whose contacts will be enrolled.

Required

Example

curl -X POST https://mailtani.com/api/v1/campaigns/1/enroll-segment \
  -H "Authorization: Bearer mk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "segment_id": 5 }'

Response 200 OK

{ "enrolled": 120, "skipped": 8 }