Update a Transactional Template via the API

Change an AhaSend transactional template’s content, subject, preview text or sender. Changes go to the draft until you publish them.

PUT /v2/accounts/{account_id}/templates/{template_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/common"
  "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()

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

  // Only the fields you set change. They go to the template's draft, the
  // same draft the dashboard edits; Publish publishes the whole draft. An
  // empty ReplyTo clears the reply-to address.
  response, _, err := client.TemplatesAPI.UpdateTemplate(ctx, accountID, templateID, requests.UpdateTemplateRequest{
    Subject: ahasend.String("Your password reset link"),
    ReplyTo: &common.SenderAddress{},
    Publish: true,
  })
  if err != nil {
    log.Fatalf("Error updating template: %v", err)
  }
  fmt.Printf("Updated template %s, has draft: %t\n", response.Name, response.HasDraft)
}

200

{
  "object": "template",
  "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>",
  "variables": [
    {
      "name": "<string>",
      "required": true
    }
  ],
  "from": {
    "email": "[e-mail]",
    "name": "Example Corp"
  },
  "reply_to": {
    "email": "[e-mail]",
    "name": "Example Corp"
  },
  "editor": "advanced",
  "has_draft": true,
  "content": {
    "text_is_custom": true,
    "mjml": "<string>",
    "html": "<string>",
    "text": "<string>"
  }
}

The AhaSend API changes a transactional template. Access requires templates:write.

Drafts and publishing:

• Changes to the subject, preview text, sender, reply-to and content go to the template’s draft. The API and the dashboard edit the same draft. A new name is not drafted: it changes when the request succeeds.
• Sends use the published copy until you publish the draft: pass publish: true, or call Publish Template.
• A publish publishes the whole draft, including changes made in the dashboard. A publish that its checks refuse changes nothing; Publish Template lists them. If the template changes between the draft write and the publish, and the publish then fails, the draft keeps the request’s changes and the name does not change.

Fields:

• A field that you leave out does not change. The one exception is the text beside a new design: see Text. from replaces the address and the name together, so a from without name clears the name. A reply_to needs a sender, so from: null also clears reply_to.
• Each field is compared with the draft, or with the published template when there is no draft. Fields equal to those values leave the draft and the published content as they are, but publish: true still publishes an existing draft. A change that makes the draft equal to the published template removes the draft: has_draft becomes false, and Get Template Draft answers 404.
• A request with no field, or with only publish: false, is refused with 400.
• You can send back a non-null content of Get Template Draft, or of Get Template when has_draft is false. While a draft exists, Get Template answers the published content, and sending it back replaces the draft’s design and text. Leave out content when you do not change it. For a simple template, send back only content.text: you can change its design only in the dashboard.

Text:

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

Content rules:

• MJML must pass strict validation. For a validation error, the message gives the line of each problem.
• Images and stylesheets must use full https:// URLs, such as https://example.com/logo.png. The API refuses relative paths, such as images/logo.png, and http:, //, data:, cid: and other schemes. A URL that starts with a template variable, such as {{ logo_url }}, is allowed. The API cannot upload files.
• The MJML, the HTML and a text written by hand can each be at most 200 KB.

If the template changes in the dashboard or through another request while this request runs, the API tries again. If that continues, the API answers 503 with a Retry-After header. Retry the request after that delay.

This operation accepts an Idempotency-Key header. A retry with the same key replays the first answer. A 503 stores no response, so a retry with the same key runs the request again. See Idempotency.

Related Guides

• API authentication, Permission scopes, Idempotency.
• Get Template Draft, 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

template_id · string<uuid> · required

Template ID

Body

application/json

Changes to a template. A field left out is not changed or checked, apart from a custom text kept beside a new design. Every field but name goes to the draft, as a dashboard save does, and a draft equal to the published copy is not kept. The draft is shared with the dashboard: publish: true, like Publish Template, publishes the whole draft, including changes made in the dashboard. name changes at once, as the last step. The editor never changes.

name · string

Template name. Spaces around it are dropped.

Required string length: 1 - 255

subject · string | null

The subject. Null or an empty string clears it. Line breaks become spaces and spaces around it are dropped.

Maximum string length: 998

preheader · string | null

The preview text. Null or an empty string clears it. Line breaks become spaces and spaces around it are dropped.

Maximum string length: 500

from · object | null

The default sender. It replaces the address and the name together, so a missing name clears the name; the reply-to is kept. Null clears the sender and the reply-to. email must be on a domain of this account with valid DNS records that is not paused.

Show child attributes

reply_to · object | null

The default reply-to address. Null clears it. It needs a sender, and its name must be empty.

Show child attributes

content · object

The content of a template write. It holds at most one of mjml and html, and at least one of mjml, html and text. The content of an advanced or html draft, or of the Template when it has no draft, can be sent back as it is: an mjml or html equal to the current one is held to the size limit but not compiled again or held to the HTML checks, and keeps the stored HTML. While a draft exists, the Template's content is the published copy's, and sending it back replaces the draft's design. Leave content out of a write that does not change it. For a simple template, send back only text: its html can be changed only in the dashboard.

The text follows these rules:

• Beside a new mjml or html, a missing text keeps the draft's text when it is custom, and that text must still render, as a sent text must; otherwise, and on a create, it makes the text from the new HTML. A null text makes the text from the new HTML, and so does a text equal to a text made from an earlier HTML: the draft's made text, or the published copy's made text when the draft does not hold that text as custom. A read content can so be sent back with a changed design. Any other text is stored as made when it equals the text made from the new HTML, and as custom otherwise. To keep a made text beside a new design, send the design first and the text in a second request.
• Otherwise a text equal to the draft's custom text keeps it; one equal to the text made from the draft's HTML is stored as made; any other is stored as custom. A null text makes the text again from the draft's HTML, and is refused when there is no HTML.

Line ends written as CRLF are stored as LF, and a blank text is refused. mjml, html and a custom text each have a size limit.

Show child attributes

publish · boolean · default: false

Publish the draft once it is written. With only publish: true, the request publishes the draft.

Response

200

application/json

Template updated. The Template object is the published copy; has_draft says whether a draft is left.

object · enum<string> · required

Object type identifier

Available options: template

id · string<uuid> · required

Pass as template_id to Create Template Message to send this template

created_at · string<date-time> · required

When the template was created

updated_at · string<date-time> · required

When the template's name or published content last changed

name · string · required

Template name, as it appears in the dashboard

subject · string · required

The published subject, set on the template page. Empty until one is published, and overridden by a send that names its own subject.

preheader · string · required

The published preview text, injected into the delivered HTML when it is set

variables · object[] · required

Every variable the design uses. A send of this template takes the values only from each recipient's substitutions. Every recipient must give a value for each required variable; if one does not, the request is rejected and no message is sent.

Show child attributes

from · object | null · required

The default sender, used by a send that names no from. Null when the template has none, and then every send must name one.

Show child attributes

Example:

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

reply_to · object | null · required

The default reply-to address, used by a send that sets no reply-to, also one that names its own from. Null when the template has none. It has the shape of a send request's reply_to; its name is always empty.

Show child attributes

Example:

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

editor · enum<string> · required

The editor the template is designed with. It never changes after the template is created.

• advanced: designed in MJML, with the dashboard's advanced editor.
• simple: designed with the dashboard's simple editor. Its HTML is made from the design and can be read but not changed through the API.
• html: an HTML template, uploaded or written by hand.

Available options: advanced, simple, html

has_draft · boolean · required

Whether the template has a draft, changes saved in the dashboard or through the API that are not published yet. Get Template Draft returns it.

content · object | null

The published content. Null when the published copy has no body, as for a template that was never published. List Templates leaves this field out; every other operation that returns a Template sets it.

Show child attributes