Email Campaigns

List, create, retrieve, and delete email campaigns

Manage email campaigns

Get a list of email campaigns

get

Returns a paginated list of the account's email campaigns, newest first.

Pagination is page-token based. Use the token query parameter together with the token, next_token, and prev_token values returned in the pagination object to navigate between pages.

Authorizations

Api-TokenstringRequired

Pass the API token in the Api-Token header

Query parameters

tokeninteger · min: 1Optional

Page number to retrieve (page-token pagination). Defaults to 1.

Default: 1Example: 1

per_pageinteger · min: 1 · max: 100Optional

Number of campaigns per page. Defaults to 50, maximum 100.

Default: 50Example: 50

searchstringOptional

Filter campaigns by name (case-insensitive partial match).

Example: spring

Responses

200

A paginated list of email campaigns.

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

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

get/api/email_campaigns

cURL

curl -X GET "https://mailtrap.io/api/email_campaigns?per_page=50&token=1" \
  -H 'Api-Token: YOUR_API_KEY'

{
  "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
      }
    }
  ],
  "pagination": {
    "token": 1,
    "prev_token": null,
    "next_token": 2,
    "first_url": "https://mailtrap.io/api/email_campaigns?per_page=50&token=1",
    "prev_url": null,
    "current_url": "https://mailtrap.io/api/email_campaigns?per_page=50&token=1",
    "next_url": "https://mailtrap.io/api/email_campaigns?per_page=50&token=2"
  }
}

Create an email campaign

post

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

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 — create a draft

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

Get an email campaign by ID

get

Returns a single email campaign.

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

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

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

get/api/email_campaigns/{email_campaign_id}

cURL

curl -X GET "https://mailtrap.io/api/email_campaigns/4567" \
  -H 'Api-Token: YOUR_API_KEY'

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

Delete an email campaign

delete

Soft-deletes an email campaign. The campaign must not be in a sending state. Returns 204 No Content on success.

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

Responses

204

The email campaign was deleted. No response body.

No content

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

delete/api/email_campaigns/{email_campaign_id}

cURL

curl -X DELETE "https://mailtrap.io/api/email_campaigns/4567" \
  -H 'Api-Token: YOUR_API_KEY'

No content

Update an email campaign

patch

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.

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

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 — edit a draft (subject + design)

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

Start an email campaign

post

Starts sending a draft campaign immediately. 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 — starting from any other state returns 422.

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

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}/start

cURL

curl -X POST "https://mailtrap.io/api/email_campaigns/4567/start" \
  -H 'Api-Token: YOUR_API_KEY'

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

Schedule an email campaign

post

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.

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

cURL

curl -X POST "https://mailtrap.io/api/email_campaigns/4567/schedule" \
  -H 'Api-Token: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "datetime": "2026-06-01T09:00:00.000Z" }'

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

Cancel a scheduled email campaign

post

Cancels a scheduled campaign, removing the pending send job and returning the campaign to the draft state. The campaign must be in the scheduled state — cancelling from any other state returns 422 ("Campaign is not scheduled").

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

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}/cancel

cURL

curl -X POST "https://mailtrap.io/api/email_campaigns/4567/cancel" \
  -H 'Api-Token: YOUR_API_KEY'

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

Terminate a sending email campaign

post

Terminates a campaign that is currently sending, aborting the in-flight send. The campaign must be in a sending state (started, queued, or paused) — terminating from any other state returns 422.

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

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}/terminate

cURL

curl -X POST "https://mailtrap.io/api/email_campaigns/4567/terminate" \
  -H 'Api-Token: YOUR_API_KEY'

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

Reset an email campaign to draft

post

Resets a campaign back to the draft state. Allowed only from the scheduled state; resetting from any other state (e.g. a sending or terminal state) returns 422.

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

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}/reset

cURL

curl -X POST "https://mailtrap.io/api/email_campaigns/4567/reset" \
  -H 'Api-Token: YOUR_API_KEY'

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

PreviousContact Events NextCampaign Stats

Last updated 2 hours ago

Was this helpful?