EmailMessage Endpoint | Sign-Up.to Permission Marketing API

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

Attribute	Type	Filter	Sort	Description
id	int	Yes	Yes	Unique ID of the message.
customoptin	bool	Yes	No	Whether the message is a custom opt-in email. Defaults to false.
defaultoptin	bool	No	No	Whether the message is the default opt-in email.
editable	bool	Yes	No	Whether the message is editable.
editor	int	No	No	The source editor. 1= "HTML input", 2="Classic Editor", 3="Campaign Designer", 4="Email Editor".
fromemail	string/null	No	No	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	string	No	No	The sender's display name.
galinkdata	bool	No	No	Enable 'utm_' data for tracked links in Google Analytics. Default is 'false'.
html	string	No	No	HTML email content.
name	string	Yes	Yes	Name of the message - this attribute is for reference only and isn't sent.
replyemail	string	No	No	The reply to email address.
friendlink	bool	No	No	Whether the email footer features a 'send to a friend' link. Default is 'false'.
subject	string	No	No	The subject of the email.
text	string	No	No	Plain text content.
tracktextlinks	bool/null	No	No	Whether links are obfuscated for tracking in the plain text content. Write-only attribute - boolean, but always returned as 'null'. Default is 'false'.
used	bool	Yes	No	Whether a message has been used in a scheduled task.
cdate	decimal	No	Yes	Creation timestamp.
mdate	decimal	No	No	Last 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

Attribute	Type	Presence	Description
id	int	Optional	Unique ID of the message.
customoptin	bool	Optional	Whether the message is a custom opt-in email. Defaults to false.
editable	bool	Optional	Whether the message is editable.
name	string	Optional	Name of the message - this attribute is for reference only and isn't sent.
used	bool	Optional	Whether a message has been used in a scheduled task.

POST /emailMessage

Attribute	Type	Presence	Description
customoptin	bool	Optional	Whether the message is a custom opt-in email. Defaults to false.
editor	int	Optional	The source editor. 1= "HTML input", 2="Classic Editor", 3="Campaign Designer", 4="Email Editor".
fromemail	string/null	Required	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	string	Required	The sender's display name.
galinkdata	bool	Optional	Enable 'utm_' data for tracked links in Google Analytics. Default is 'false'.
html	string	Required	HTML email content.
name	string	Required	Name of the message - this attribute is for reference only and isn't sent.
replyemail	string	Required	The reply to email address.
friendlink	bool	Optional	Whether the email footer features a 'send to a friend' link. Default is 'false'.
subject	string	Required	The subject of the email.
text	string	Required	Plain text content.
tracktextlinks	bool/null	Optional	Whether 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 [...]".

If setting customoptin to true, the html and text fields must contain the following personalisation tags:

"html": "<signup_link value=\"%sut_optin%\" name=\"opt-in\"> click here to activate your subscription</signup_link>",
"text": "<signup_name value=\"optin\" alt=\"\">"

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

Attribute	Type	Presence	Description
id	int	Required	Unique ID of the message.
customoptin	bool	Optional	Whether the message is a custom opt-in email. Defaults to false.
fromemail	string/null	Optional	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	string	Optional	The sender's display name.
galinkdata	bool	Optional	Enable 'utm_' data for tracked links in Google Analytics. Default is 'false'.
html	string	Optional	HTML email content.
name	string	Optional	Name of the message - this attribute is for reference only and isn't sent.
replyemail	string	Optional	The reply to email address.
friendlink	bool	Optional	Whether the email footer features a 'send to a friend' link. Default is 'false'.
subject	string	Optional	The subject of the email.
text	string	Optional	Plain text content.
tracktextlinks	bool/null	Optional	Whether links are obfuscated for tracking in the plain text content. Write-only attribute - boolean, but always returned as 'null'. Default is 'false'.

If setting customoptin to true, the html and text fields must contain the following personalisation tags:

"html": "<signup_link value=\"%sut_optin%\" name=\"opt-in\"> click here to activate your subscription</signup_link>",
"text": "<signup_name value=\"optin\" alt=\"\">"

DELETE /emailMessage or /emailMessage/:id

Attribute	Type	Presence	Description
id	int	Required	Unique 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

Code	Subcode	Message	Description
423	10	Message $id is locked	This 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,
    "customoptin":    false,
    "defaultoptin":   false,
    "editable":       false,
    "editor":         1,
    "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
}