Update an email campaign

Updates an existing draft campaign. Only the provided attributes are changed. To edit the template (subject or design), pass template_attributes — the campaign's template is always edited in place, and only the template sub-fields you provide change (see the template_attributes schema for the partial-update rules).

Update accepts the same fields as create, including the audience (contact_list_ids/contact_segment_ids). The typical flow is to create a draft, add its design and audience over one or more updates, then schedule or start it via the dedicated schedule/start action endpoints.

Only draft campaigns can be updated — editing a campaign that is already scheduled/sending returns 422.

patch

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

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.

namestringOptional

Campaign name.

Example: Spring Sale

domain_idinteger · int64Optional

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_partstringOptional

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

Example: news

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

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 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

patch/api/email_campaigns/{email_campaign_id}

curl -X PATCH "https://mailtrap.io/api/email_campaigns/4567" \
  -H 'Api-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Spring Sale (updated)",
    "template_attributes": {
      "subject": "New subject",
      "body_html": "<html><body><h1>Hi {{first_name}}!</h1><p><a href=\"__unsubscribe_url__\">Unsubscribe</a></p></body></html>"
    }
  }'

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