Skip to main content

Scheduling

A campaign sends either immediately or at a scheduled future time. Scheduled sends are cancellable until the moment delivery starts.

Send modes​

ModeBehaviorAPI
Send NowDelivery starts as soon as the platform accepts the request.POST /v2/email-marketing/{campaignId}/send (or /create-send to combine)
ScheduleDelivery starts at scheduledAt. Cancellable.POST /v2/email-marketing with scheduledAt plus later /send or auto-launch at scheduled time
Send Time OptimizationPer-recipient send time picked by Mailtarget based on recipient open history.Dashboard option, plus optionsAttributes field on API

Schedule a campaign​

curl https://api.mailtarget.co/v2/email-marketing \
  -X POST \
  -H "Authorization: Bearer $MAILTARGET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject":     "Tomorrow's deal",
    "senderName":  "Your Brand",
    "senderEmail": "hello@your-verified-domain.com",
    "body":        "<p>Don'\''t miss it.</p>",
    "recipients":  { "labelIds": ["lbl_deal_subscribers"] },
    "scheduledAt": "2026-05-09T08:00:00+07:00"
  }'

scheduledAt accepts ISO 8601 with timezone offset. Use the recipient timezone or your account timezone consistently.

Cancel a scheduled send​

curl https://api.mailtarget.co/v2/email-marketing/{campaignId}/cancel-schedule \
  -X POST \
  -H "Authorization: Bearer $MAILTARGET_API_KEY"

Cancellation works only while status is scheduled. Once status flips to sending, cancel is rejected. The platform commits to delivery before any recipient receives the first message, so partial cancellation is not supported.

Send Time Optimization​

Send Time Optimization (STO) lets the platform pick the best send time per recipient based on their historical open behavior. Different recipients in the same campaign receive at different times, all within a window you set.

When to use STO:

  • Recipient timezones span multiple regions.
  • Open rates matter more than send-time consistency.
  • The campaign content is not time-sensitive (no flash sale, no breaking news).

When NOT to use STO:

  • Time-sensitive content (flash sale, ticket window opening).
  • Live or webinar reminders that must hit at a specific moment.
  • A/B tests where the variable is send time itself (use a regular schedule with fixed time).

Configure STO in the dashboard send step or via optionsAttributes on the campaign object. Pick a window (typically 24 hours) and the platform optimizes within it.

Timezone behavior​

Mailtarget interprets scheduledAt literally. If you send 2026-05-09T08:00:00+07:00, the platform launches at 08:00 Asia/Jakarta time on that date.

Recommendations:

  • Always include timezone offset. A naked datetime without offset risks misinterpretation across server timezones.
  • Use recipient-relevant timezone. If your audience is Indonesian, schedule in +07:00. If global, see Send Time Optimization.
  • Account-default timezone is set in account settings. Used for dashboard display. Not used for parsing API datetimes.

Common mistakes​

SymptomLikely cause
Campaign sent immediately despite scheduled timescheduledAt in the past or wrong format. The platform falls back to immediate send.
Cancel returns 409 ConflictCancel attempted after sending status. Too late.
All STO recipients got the email at the same timeInsufficient open history for the recipient set. STO falls back to a default send time when data is missing.
Schedule shows wrong time in dashboardAccount timezone mismatch with the schedule timezone offset. Both are correct, but the display surface differs.

How scheduling affects reports​

A scheduled campaign shows up in reports at launch time, not at create time. Engagement aggregates accumulate from delivery onward. See Reports for the timing of report freshness.