Schedule an email campaign

Schedules a draft campaign to start sending at a future time. Runs full sending validation (the template must have a body_html design, the audience and verified sending domain must be set, billing within limits); on failure the request returns 422 and the campaign stays a draft. The campaign must be in the draft state — scheduling from any other state returns 422. After scheduling, the time is reported back in current_state_metadata.scheduled_at.

post

Authorizations

Api-TokenstringRequired

Pass the API token in the Api-Token header

Path parameters

email_campaign_idinteger · int64 · min: 1Required

Unique identifier of the email campaign

Example: 4567

Body

When to start sending the campaign.

datetimestring · date-timeRequired

When to send the campaign (ISO 8601). Must be in the future and no more than 1 month ahead, otherwise the request is rejected with 422.

Example: 2026-10-01T09:00:00.000Z

Responses

200

A single email campaign.

application/json

401

Authentication failed — missing or invalid API token.

application/json

403

The API token does not have permission to access this resource.

application/json

404

The requested email campaign was not found.

application/json

422

The lifecycle action was rejected — the campaign was in a state that does not allow the action, the datetime was invalid, or sending validation failed.

application/json

429

Too many requests. The public API is rate limited to 150 requests per 10 seconds per API token. Retry after the window resets (see the x-ratelimit-reset header).

application/json

post/api/email_campaigns/{email_campaign_id}/schedule

# Must be in the future and no more than 1 month ahead.
DATETIME=$(date -u -d '+1 day' +%Y-%m-%dT%H:%M:%S.000Z 2>/dev/null || date -u -v+1d +%Y-%m-%dT%H:%M:%S.000Z)

curl -X POST "https://mailtrap.io/api/email_campaigns/4567/schedule" \
  -H 'Api-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d "{ \"datetime\": \"$DATETIME\" }"

{
  "data": {
    "id": 4567,
    "domain_id": 4321,
    "domain_name": "acme.com",
    "name": "Spring Sale",
    "from_local_part": "news",
    "from_display_name": "Acme Marketing",
    "reply_to": {
      "display_name": "Acme Support",
      "local_part": "support",
      "domain": "acme.com"
    },
    "current_state": "draft",
    "current_state_metadata": {
      "reason": "text",
      "error": "text",
      "errors": [
        {
          "message": "Invalid recipient address",
          "rcpt_index": 0
        }
      ],
      "scheduled_at": "2026-06-01T09:00:00.000Z"
    },
    "created_at": "2026-05-01T10:15:00.000Z",
    "updated_at": "2026-05-02T09:00:00.000Z",
    "last_started_at": "2026-05-03T12:00:00.000Z",
    "last_started_at_date": "2026-05-03",
    "recipient_total_count": 1500,
    "contact_list_ids": [
      55,
      56
    ],
    "contact_segment_ids": [
      12
    ],
    "delivery_mode": "rapid",
    "delivery_options": {
      "emails_per_hour": 1000
    },
    "template": {
      "id": 789,
      "subject": "Spring is here — 30% off",
      "merge_tags": [
        "first_name"
      ],
      "body_html": "<html><body><h1>Hi {{first_name}}!</h1><p><a href=\"__unsubscribe_url__\">Unsubscribe</a></p></body></html>",
      "body_text": null
    }
  }
}