Email Campaigns
List, create, retrieve, and delete email campaigns
Manage email campaigns
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.
Pass the API token in the Api-Token header
Page number to retrieve (page-token pagination). Defaults to 1.
1Example: 1Number of campaigns per page. Defaults to 50, maximum 100.
50Example: 50Filter campaigns by name (case-insensitive partial match).
springA paginated list of email campaigns.
Authentication failed — missing or invalid API token.
The API token does not have permission to access this resource.
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).
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"
}
}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).
Pass the API token in the Api-Token header
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.
Campaign name.
Spring SaleID of the verified sending domain used for the campaign, as returned by the Sending Domains endpoints.
4321Display name shown in the From header.
Acme MarketingLocal part (before the @) of the From address.
newsHow the campaign is delivered. rapid sends as fast as possible; gradual throttles
sending to delivery_options.emails_per_hour.
rapidPossible values: 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.
[55,56]IDs of contact segments to send to. Treated as the full set of included segments.
[12]A single email campaign.
Authentication failed — missing or invalid API token.
The API token does not have permission to access this resource.
The request was rejected due to validation errors.
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).
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
}
}
}Returns a single email campaign.
Pass the API token in the Api-Token header
Unique identifier of the email campaign
4567A single email campaign.
Authentication failed — missing or invalid API token.
The API token does not have permission to access this resource.
The requested email campaign was not found.
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).
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
}
}
}Soft-deletes an email campaign. Returns 204 No Content on success.
Only draft campaigns can be deleted — deleting a campaign that is already scheduled/sending returns 422. A campaign that has been started never returns to draft, so it can no longer be deleted. A scheduled campaign can be returned to draft first via the cancel or reset action endpoints.
Pass the API token in the Api-Token header
Unique identifier of the email campaign
4567The email campaign was deleted. No response body.
No content
Authentication failed — missing or invalid API token.
The API token does not have permission to access this resource.
The requested email campaign was not found.
The request was rejected due to validation errors.
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).
curl -X DELETE "https://mailtrap.io/api/email_campaigns/4567" \
-H 'Api-Token: YOUR_API_KEY'
No content
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.
Pass the API token in the Api-Token header
Unique identifier of the email campaign
4567Campaign 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.
Campaign name.
Spring SaleID of the verified sending domain used for the campaign, as returned by the Sending Domains endpoints.
4321Display name shown in the From header.
Acme MarketingLocal part (before the @) of the From address.
newsHow the campaign is delivered. rapid sends as fast as possible; gradual throttles
sending to delivery_options.emails_per_hour.
rapidPossible values: 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.
[55,56]IDs of contact segments to send to. Treated as the full set of included segments.
[12]A single email campaign.
Authentication failed — missing or invalid API token.
The API token does not have permission to access this resource.
The requested email campaign was not found.
The request was rejected due to validation errors.
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).
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
}
}
}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.
Pass the API token in the Api-Token header
Unique identifier of the email campaign
4567A single email campaign.
Authentication failed — missing or invalid API token.
The API token does not have permission to access this resource.
The requested email campaign was not found.
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.
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).
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
}
}
}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.
Pass the API token in the Api-Token header
Unique identifier of the email campaign
4567When to start sending the campaign.
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.
2026-10-01T09:00:00.000ZA single email campaign.
Authentication failed — missing or invalid API token.
The API token does not have permission to access this resource.
The requested email campaign was not found.
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.
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).
# 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
}
}
}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").
Pass the API token in the Api-Token header
Unique identifier of the email campaign
4567A single email campaign.
Authentication failed — missing or invalid API token.
The API token does not have permission to access this resource.
The requested email campaign was not found.
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.
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).
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
}
}
}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.
Pass the API token in the Api-Token header
Unique identifier of the email campaign
4567A single email campaign.
Authentication failed — missing or invalid API token.
The API token does not have permission to access this resource.
The requested email campaign was not found.
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.
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).
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
}
}
}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.
Pass the API token in the Api-Token header
Unique identifier of the email campaign
4567A single email campaign.
Authentication failed — missing or invalid API token.
The API token does not have permission to access this resource.
The requested email campaign was not found.
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.
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).
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
}
}
}Last updated
Was this helpful?