EmailMessage v1.2

Describes the content and supporting attributes of an email message.

What can I do with emailMessage?

Send messages to your subscribers using tasks.

  • A message_id must be provided when creating a new task.
  • A message is not editable if a task references its id. Filter by editable to show a list of messages which can or cannot be modified.
  • You can sort and filter messages by the name field.
  • Messages can be created for both email and SMS channels.

In all cases, tracktextlinks behaviour is write-only. The attribute is a boolean, defaulting to 'false', but it will be always returned as "null".

GET /emailMessage or /emailMessage/:id

AttributeTypeFilterSortDescription
id
intYesYesUnique ID of the message.
editable
boolYesNoWhether the message is editable.
fromemail
string/nullNoNo

The sender's email address. The value of the attribute must match a pre-configured value in your account on the Sign-Up.to platform. Default is 'null' if no pre-configured addresses exist.

fromname
stringNoNoThe sender's display name.
galinkdata
boolNoNoEnable 'utm_' data for tracked links in Google Analytics. Default is 'false'.
html
stringNoNoHTML email content.
name
stringYesYes

Name of the message - this attribute is for reference only and isn't sent.

replyemail
stringNoNoThe reply to email address.
friendlink
boolNoNoWhether the email footer features a 'send to a friend' link. Default is 'false'.
subject
stringNoNoThe subject of the email.
text
stringNoNoPlain text content.
tracktextlinks
bool/nullNoNoWhether links are obfuscated for tracking in the plain text content. Write-only attribute - boolean, but always returned as 'null'. Default is 'false'.
used
boolYesNoWhether a message has been used in a scheduled task.
cdate
decimalNoYesCreation timestamp.
mdate
decimalNoNoLast modification timestamp.

For your convenience, html links are obuscated with tracking URIs on POST and PUT. GET requests return this parsed version (not the original).

A message will no longer be editable once a scheduled task has been created for the message. Messages are also not editable via the API if they were created using the Campaign Designer or Classic Editor in the Sign-Up.to platform.

HEAD /emailMessage or /emailMessage/:id

AttributeTypePresenceDescription
id
intOptionalUnique ID of the message.
editable
boolOptionalWhether the message is editable.
name
stringOptional

Name of the message - this attribute is for reference only and isn't sent.

used
boolOptionalWhether a message has been used in a scheduled task.

POST /emailMessage

AttributeTypePresenceDescription
fromemail
string/nullRequired

The sender's email address. The value of the attribute must match a pre-configured value in your account on the Sign-Up.to platform. Default is 'null' if no pre-configured addresses exist.

fromname
stringRequiredThe sender's display name.
galinkdata
boolOptionalEnable 'utm_' data for tracked links in Google Analytics. Default is 'false'.
html
stringRequiredHTML email content.
name
stringRequired

Name of the message - this attribute is for reference only and isn't sent.

replyemail
string

Required

The reply to email address.
friendlink
boolOptionalWhether the email footer features a 'send to a friend' link. Default is 'false'.
subject
stringRequiredThe subject of the email.
text
stringRequiredPlain text content.
tracktextlinks
bool/nullOptionalWhether links are obfuscated for tracking in the plain text content. Write-only attribute - boolean, but always returned as 'null'. Default is 'false'.

The html attribute supports both personalisation and dynamic content. Use these features to create engaging, tailored content for each subscriber!

Please note, in accordance with RFC 5321 section 4.5.3.1.6 - "The maximum total length of a text line including the <CRLF> is 1000 octets [...]".

The html, text and subject fields are converted to 'Window-1252'/CP-1252. Invalid conversion will result in an error.

PUT /emailMessage or /emailMessage/:id

AttributeTypePresenceDescription
id
intRequiredUnique ID of the message.
fromemail
string/nullOptional

The sender's email address. The value of the attribute must match a pre-configured value in your account on the Sign-Up.to platform. Default is 'null' if no pre-configured addresses exist.

fromname
stringOptionalThe sender's display name.
galinkdata
boolOptionalEnable 'utm_' data for tracked links in Google Analytics. Default is 'false'.
html
stringOptionalHTML email content.
name
stringOptional

Name of the message - this attribute is for reference only and isn't sent.

replyemail
stringOptionalThe reply to email address.
friendlink
boolOptionalWhether the email footer features a 'send to a friend' link. Default is 'false'.
subject
stringOptionalThe subject of the email.
text
stringOptionalPlain text content.
tracktextlinks
bool/nullOptionalWhether links are obfuscated for tracking in the plain text content. Write-only attribute - boolean, but always returned as 'null'. Default is 'false'.

DELETE /emailMessage or /emailMessage/:id

AttributeTypePresenceDescription
id
intRequiredUnique ID of the message.

If a message is referenced by a task when DELETE is issued, the associated task will not be cancelled. The message is made available to the task (soft deleted) but cannot be requested by any subsequent GET requests. In this case, it could be considered good practice to cancel a task before issuing the DELETE.

Error codes

CodeSubcodeMessageDescription
423
10
Message $id is lockedThis message is scheduled to be sent or has been sent.
400
11
(Dynamic content syntax error)A dynamic content syntax error - please see documentation for more info.

Please see error handling for more information on error codes.

Examples

Have you seen our example of this endpoint being used with other endpoints?

JSON response

{
    "id"              101010101,
    "editable":       false,
    "fromemail":      "mailbox@example.com",
    "fromname":       "JSmith Ltd",
    "galinkdata":     false,
    "html":           "<html><head><title></title></head><body><p>HTML</p></body></html>",
    "name":           "Example email",
    "replyemail":     "mailbox@example.com"
    "friendlink":     false,
    "subject":        "Example subject",
    "text":           "plain text",
    "tracktextlinks": null,
    "used":           true,
    "cdate":          1234966741,
    "mdate":          1234966741
}