Update a Campaign via the API

Change a draft AhaSend marketing campaign: its name, sender, reply-to, lists, subject, preview text or design. Only a draft campaign can be changed.

PUT /v2/accounts/{account_id}/campaigns/{campaign_id}

AhaSend Go SDK

Go

package main

import (
  "context"
  "fmt"
  "log"
  "os"

  "github.com/AhaSend/ahasend-go"
  "github.com/AhaSend/ahasend-go/api"
  "github.com/AhaSend/ahasend-go/models/requests"
  "github.com/google/uuid"
)

func main() {
  client := api.NewAPIClient(api.WithAPIKey(os.Getenv("AHASEND_API_KEY")))
  accountID := uuid.MustParse(os.Getenv("AHASEND_ACCOUNT_ID"))
  ctx := context.Background()

  campaignID := uuid.MustParse("11111111-1111-4111-8111-111111111111")

  // Only the fields you set change, and only while the campaign is a
  // draft. A ReplyTo that points at "" clears the reply-to address.
  response, _, err := client.CampaignsAPI.UpdateCampaign(ctx, accountID, campaignID, requests.UpdateCampaignRequest{
    Subject: ahasend.String("Our news for October"),
    ReplyTo: ahasend.String(""),
  })
  if err != nil {
    log.Fatalf("Error updating campaign: %v", err)
  }
  fmt.Printf("Updated campaign %s, %d issues left\n", response.Name, len(response.Issues))
}

200

{
  "object": "campaign",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "name": "<string>",
  "subject": "<string>",
  "preheader": "<string>",
  "from": {
    "email": "[e-mail]",
    "name": "Example Corp"
  },
  "reply_to": "[e-mail]",
  "status": "draft",
  "status_reason": "<string>",
  "send_at": "2023-11-07T05:31:56Z",
  "send_resumes_at": "2023-11-07T05:31:56Z",
  "finished_at": "2023-11-07T05:31:56Z",
  "list_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "editor": "advanced",
  "content": {
    "text_is_custom": true,
    "mjml": "<string>",
    "html": "<string>",
    "text": "<string>"
  },
  "ready": true,
  "issues": [
    {
      "code": "sender_missing",
      "message": "<string>"
    }
  ]
}

The AhaSend API changes a draft campaign. Access requires campaigns:write.

A campaign that is not a draft answers 409 with campaign is not a draft. To change a scheduled campaign, unschedule it first. See Changes only to drafts.

Fields:

• A field that you leave out does not change and is not checked. A request with no field is refused with 400.
• null clears subject, preheader, from or reply_to. When you clear from, reply_to stays.
• list_ids replaces all lists of the campaign. A list that does not exist is refused with 400.
• template_id is not accepted: only Create Campaign can copy a campaign template. A request with template_id is refused with 400 as an unknown field.
• The fields follow the rules of Create Campaign.

Design:

• You cannot change the editor of the design.
• A campaign with no design yet needs content.mjml or content.html, which sets its editor.
• For a simple design, send only content.text: you can change the design only in the dashboard.
• When you send a new content.mjml or content.html and leave out content.text, a text written by hand stays, and a text made from the HTML is made again from the new HTML. Send content.text as null to make the text again from the new HTML, also when the text was written by hand.
• A text written by hand that stays must still render. If it holds a {{, {% or {# that cannot be rendered, the request is refused with 400.
• The content follows the content rules of Create Campaign.

Changes from the dashboard:

• The API and the dashboard change the same campaign. The request waits for other changes to the same campaign to finish, and a send that starts after the request uses the change.
• When a dashboard editor is open on the same campaign, the design that is saved last is kept.

This operation accepts an Idempotency-Key header. A refusal from this operation is stored for the key, so send a corrected request with a new key. See Idempotency and campaign retries.

Related Guides

• API authentication, Permission scopes, Idempotency.
• Get Campaign, API errors, API rate limits.

Authorizations

Authorization · string · header · required

API key for authentication. Non-empty Security Requirement values are AhaSend API-key roles. Roles listed within one requirement object are jointly required; separate requirement objects are alternatives.

Headers

Idempotency-Key · string

Optional idempotency key for safe request retries. Must be a unique string for each logical request. An identical request with a completed stored outcome returns the original status and body. An in-progress execution returns 409, a changed method/path/body returns 422, and a released 5xx execution may run again. Keys for non-secret responses expire after 24 hours. API-key create responses include a one-time secret_key, so successful encrypted replay responses for those operations expire after 5 minutes.

Maximum string length: 255

Path Parameters

account_id · string<uuid> · required

Account ID

campaign_id · string<uuid> · required

Campaign ID

Body

application/json

Changes to a draft campaign. A field left out is neither changed nor checked. The design's editor never changes.

name · string

Campaign name. Spaces around it are dropped.

Required string length: 1 - 255

subject · string | null

The subject line, cleaned as on create. Null clears it.

preheader · string | null

The preview text, cleaned as on create. Null clears it.

from · object | null

The sender, as on create. Null clears the sender; reply_to stays as it is.

Show child attributes

reply_to · string<email> | null

The reply-to address, as on create. Null clears it.

list_ids · string<uuid>[]

The lists to send to, which replace the campaign's lists, as on create.

Required array length: 1 - 50 elements

content · object

The content of the design, by the rules of TemplateContentInput, in the design's editor. For a simple design, send only text. A campaign with no design yet needs mjml or html, which sets its editor.

Show child attributes

Response

200

application/json

Campaign updated

A campaign as List Campaigns returns it, without its lists, content and issues.

object · enum<string> · required

Object type identifier

Available options: campaign

id · string<uuid> · required

Campaign ID

created_at · string<date-time> · required

When the campaign was created

updated_at · string<date-time> · required

When the campaign's own fields last changed

name · string · required

Campaign name, as it appears in the dashboard. Recipients do not see it.

subject · string | null · required

The subject line. Null until one is set.

preheader · string | null · required

The preview text, which most inboxes show after the subject. Null until one is set.

from · object | null · required

The sender. Null until a complete sender is set, and when its domain was deleted. name is an empty string when the campaign has no sender name, so the object can be sent back as it is.

Show child attributes

Example:

{
  "email": "[e-mail]",
  "name": "Example Corp"
}

reply_to · string<email> | null · required

The reply-to address. Null when none is set.

status · enum<string> · required

Where the campaign is in its life. Only a draft can be changed or deleted.

• draft: being prepared.
• validating: scheduled, and its lists are being checked.
• waiting_for_review: held for a review before it sends.
• scheduled: accepted, waiting for its send time.
• sending: sending now.
• paused: sending stopped for now; status_reason says why.
• sent: every message was sent.
• canceled: stopped before it finished; status_reason says why.
• failed: could not be sent; status_reason says why.

Available options: draft, validating, waiting_for_review, scheduled, sending, paused, sent, canceled, failed

status_reason · string | null · required

Why the campaign is in its status, when there is a reason to give. Null otherwise.

send_at · string<date-time> | null · required

When the campaign sends or sent, in UTC. Null until it is scheduled.

send_resumes_at · string<date-time> | null · required

When a send that reached the account's daily marketing limit continues, in UTC. Null otherwise.

finished_at · string<date-time> | null · required

When the send ended, in UTC. Null until then.

list_ids · string<uuid>[] · required

The lists the campaign sends to, in the order they were saved. A list that was deleted is left out.

editor · enum<string> | null · required

The editor of the campaign's design. Null while the campaign has no design.

Available options: advanced, simple, html

content · object | null · required

The content of the campaign's design. Null while it has no design, or its design has neither HTML nor text.

Show child attributes

ready · boolean | null · required

Whether the draft has no issue, so it can be sent. Null unless the campaign is a draft.

issues · object[] | null · required

The reasons the draft cannot be sent yet, in a fixed order; empty when it is ready. Null unless the campaign is a draft.

Show child attributes