Create an email campaign

Creates a new email campaign. The campaign must reference an existing sending domain via domain_id, and include a template subject within template_attributes.

Create accepts the same fields as update — pick the audience with contact_list_ids/contact_segment_ids, set delivery options, and add the design via template_attributes.body_html. The campaign is always created in the draft state; scheduling and starting are separate actions (see the schedule and start endpoints).

post

Authorizations

Api-TokenstringRequired

Pass the API token in the Api-Token header

Body

Campaign attributes. Both create and update accept the same fields. Create and update only manage attributes and audience — the campaign always stays in draft; scheduling and starting are performed via the dedicated lifecycle action endpoints.

namestringRequired

Campaign name.

Example: Spring Sale

domain_idinteger · int64Required

ID of the verified sending domain used for the campaign, as returned by the Sending Domains endpoints.

Example: 4321

from_display_namestringOptional

Display name shown in the From header.

Example: Acme Marketing

from_local_partstringRequired

Local part (before the @) of the From address.

Example: news

template_attributesobjectRequired

delivery_modestring · enumOptional

How the campaign is delivered. rapid sends as fast as possible; gradual throttles sending to delivery_options.emails_per_hour.

Example: rapidPossible values:

contact_list_idsinteger · int64[]Optional

IDs of contact lists to send to. Treated as the full set of included lists — lists not listed are removed. Combine with contact_segment_ids to target both.

Example: [55,56]

contact_segment_idsinteger · int64[]Optional

IDs of contact segments to send to. Treated as the full set of included segments.

Example: [12]

Responses

201

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

422

The request was rejected due to validation errors.

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

curl -X POST "https://mailtrap.io/api/email_campaigns" \
  -H 'Api-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Spring Sale",
    "domain_id": 4321,
    "from_display_name": "Acme Marketing",
    "from_local_part": "news",
    "reply_to": {
      "display_name": "Acme Support",
      "local_part": "support",
      "domain": "acme.com"
    },
    "template_attributes": { "subject": "Spring is here — 30% off" }
  }'

{
  "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
    }
  }
}