Page tree
Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 15 Next »



Getting started

This API provides web services for accessing to the same features that are available with SMTP+ v2. Also the performances, the aggregation policies and the usage restrictions (i.e. do not use it for promotional emails) are exactly the same as SMTP+ v2.

The parameters that are specified with message headers in SMTP+ v2 are here handled as fields of an object that is passed to the web services. For more details about these parameters please check out the examples that are provided for SMTP+ v2

Best Practices

  • Avoid aggregation types that create several dozens of messages per day in your admin console. CampaignCode field is a great way to aggregate messages in order to reduce created messages and, at the same time obtain meaningful statistics. If you don't specify the CampaignCode value,  the default value for the SMTP+ user applies (this value is set in the admin console)
  • Always check returned value. Since most of the returned errors code are due to bad input parameters, any retry attempt will fail when returned code is HTTP 403.

 

Warnings

If you are using a trial or a developer account only a few messages can be sent, while for paying accounts such volume restrictions do not apply. In any case, delivery throughput cannot exceed the speed that you purchased for your account.

If you change the password of your SMTP+ account, then any application based on it, API included, will stop working. 

Do not rely too much on the "Priority" field, many restrictions apply on it because its value is properly handled only at a specific stage of message workflow, there is no way to guarantee that the order based on priority value is kept at all delivery stages.

Please be aware that, as with SMTP relay, methods that are used to send emails are asynchronous, hence a successful return code means that request is correct and it has been added to a queue, but it does not guarantee the message delivery (e.g. queueing and processing was ok but specified recipient is unreachable or unsubscribed)

 

 

 


Authentication

To access resources and to use the methods, you must have an active account with an enabled SMTP+ user (SMTP+ users have the "sNNNNN_NN" format). Usename and password must be included in each request through "User" parameter .

"User":{"Username":"YourSmtpPlusUsername","Secret":"YourSmtpPlusPassword"}

An error may be returned when SMTP+ user is blocked, in this case you could use "ListUserInfo" method to get more details.

 


Resources

 Messages

This section includes the methods that can be used to send transactional emails. Use "SendMessage" when you need to specify a completely different content for each message, while you can use "SendTemplate" and specify merge tags if you want to pick the body of an existing content and simply customize some of its parts. Each of these two method provides the same level of performances, you can freely use the one that better fits your needs in terms of data to be passed to the method. 

SendMessage

DescriptionThis method allows sending of a message to multiple recipients, the message content is passed as input with HTML code or plain text. The message may also include attachments and embedded images.
HTTP MethodPOST
URLhttps://send.mailup.com/API/v2.0/messages/sendmessage
Reference
 Click here to learn more about request parameters

The method takes as input the document JSON or XML that has the structure MessageDTO defined in the tables below.

MessageDTO
ParameterTypeDescription
SubjectStringthe subject of the message
HtmlHtmlDTOHTML part of the message (specify only the HTML inside the body tag)
TextStringthe plain text part of the message
FromEmailAddressDTOthe sender
ToList<EmailAddressDTO>the list of recipients in To header
CcList<EmailAddressDTO>the list of recipients in Cc header
BccList<EmailAddressDTO>the list of recipients in Bcc
ReplyToStringThe email address to be added into Reply-To header
CharSetStringThe charset of the message body
ExtendedHeadersList<NameValueDTO>List of custom headers (only SMTP headers that are approved by MailUp will be added)
AttachmentsList<MessagePartDTO>List of attachments
EmbeddedImagesList<MessagePartDTO>list of embedded images
XSmtpAPIXSmtpAPIDTOthe X-SMTPAPI header value, used for custom aggregations and configurations
UserSmtpUserDTOthe SMTP+ user credentials

 

HtmlDTO
ParameterTypeDescription
DocTypeStringThe DOCTYPE directive
HeadStringThe head content
BodyStringThe body content
BodyTagStringthe body tag, default is "< body>"
EmailAddressDTO
ParameterTypeDescription
NameStringthe name
EmailStringthe email address
NameValueDTO
ParameterTypeDescription
NStringthe name of the parameter
VStringthe value of the parameter
MessagePartDTO
ParameterTypeDescription
FilenameStringthe file name
ContentIdStringthe Content-Id value
BodyArray of Bytethe array of byte of the content
XSmtpAPIDTO
ParameterTypeDescription
CampaignNameStringThe name used for the aggregated campaign
CampaignCodeStringThe campaign code which determines the aggregation
HeaderBooleanAdd or not the MailUp header to the message
FooterBooleanAdd or not the MailUp footer to the message
ClickTrackingBooleanUse the click tracking
ViewTrackingBooleanUse the view tracking
PriorityIntegerSet the priority of the message (1 high - 5 low )
ScheduleDateTimeSchedule date and time of the message
DynamicFieldsList<NameValueDTO>List of merge tags and dynamic field of the recipient
CampaignReportStringName of the aggregated campaign report
SkipDynamicFieldsBooleanskip merge tags evaluation
SmtpUserDTO
ParameterTypeDescription
UsernameStringthe username
SecretStringthe password

 

 

 Click here to learn more about response parameters


SendResponseDTO
ParameterTypeDescription
StatusStringthe status of the response can be "done" or "error"
CodeStringthe result code (see the Error Code table)
MessageStringthe result message

 


 JSON request (example)
 Click here to expand...
{
"Html":
{
"DocType":null,
"Head":null,
"Body":"<div>Hello Mr. [firstname] [lastname] !!!</div><br><img width=\"600\" height=\"397\" src=\"cid:img001\">",
"BodyTag":"<body>"
},
"Text":"Hello world!!!",
"Subject":"Hello friend!",
"From":{"Name":"Test User","Email":"test@mailup.it"},
"To":[{"Name":"Massimo","Email":"info@mailup.it"}],
"Cc":[],
"Bcc":[],
"ReplyTo":null,
"CharSet":"utf-8",
"ExtendedHeaders":null,
"Attachments":null,
"EmbeddedImages":
[
{
"Filename":"Image.jpg",
"ContentId":"img001",
"Body":"..."
}
],
"XSmtpAPI":
{
"CampaignName":"Test Campaign",
"CampaignCode":"1001",
"Header":null,
"Footer":null,
"ClickTracking":null,
"ViewTracking":null,
"Priority":null,
"Schedule":null,
"DynamicFields":[{"N":"firstname","V":"Mario"},{"N":"lastname","V":"Rossi"}],
"CampaignReport":null,
"SkipDynamicFields":null
},
"User":{"Username":"sNNNNN_NN","Secret":"..."}
}
JSON response (example)

Example of a successful response:

{
"Status":"done",
"Code":"0",
"Message":"Ok"
}

Example of error:

{
"Status":"error",
"Code":"102",
"Message":"The operation is not authorized."
}

SendTemplate

DescriptionThis method allows sending of a message to multiple recipients, the message content (both HTML body and plain text) is obtained by specifying the ID of a MailUp message that stored in the MailUp admin console.
The message may also include attachments and embedded images
HTTP MethodPOST
URLhttps://send.mailup.com/API/v2.0/messages/sendtemplate 
Reference
 Click here to learn more about request parameters


TemplateDTO
ParameterTypeDescription
SubjectStringthe subject of the message
TemplateIdIntegerID of the MailUp message whose content has to be used. Only messages that belong to the same list of SMTP+ user can be accepted
FromEmailAddressDTOSender (both name and email)
ToList<EmailAddressDTO>the list of recipients in To header
CcList<EmailAddressDTO>the list of recipients in Cc header
BccList<EmailAddressDTO>the list of recipients in Bcc
ReplyToStringThe email address to be added into Reply-To header
CharSetStringThe charset of the message body
ExtendedHeadersList<NameValueDTO>List of custom headers (only SMTP headers that are approved by MailUp will be added)
AttachmentsList<MessagePartDTO>List of attachments
EmbeddedImagesList<MessagePartDTO>list of embedded images
XSmtpAPIXSmtpAPIDTOthe X-SMTPAPI header value, used for custom aggregations and configurations
UserSmtpUserDTOthe SMTP+ user credentials

 See the SendMessage reference for the definition of the others DTOs (EmailAddressDTO, NameValueDTO, ...)

 

 Click here to learn more about response parameters


SendResponseDTO
ParameterTypeDescription
StatusStringthe status of the response can be "done" or "error"
CodeStringthe result code (see the Error Code table)
MessageStringthe result message

 

JSON request (example)
 Click here to expand...
{
"TemplateId":694,
"Subject":"Test message from template",
"From":{"Name":"Test User","Email":"test@example.com"},
 "To":[{"Name":"Max","Email":"info@example.com"}],
"Cc":[],
"Bcc":[],
"ReplyTo":null,
"CharSet":"utf-8",
"ExtendedHeaders":null,
"Attachments":null,
"EmbeddedImages":null,
"XSmtpAPI":null,
"User":{"Username":"sNNNNN_NN","Secret":"..."}
}
JSON response (example)

Example of a successful response:

{
"Status":"done",
"Code":"0",
"Message":"Ok"
}

 

Example of error:

{
"Status":"error",
"Code":"111",
"Message":"The template is not found."
}

 

Users

Use ListUserInfo to retrieve status details about current SMTP+ user or other SMTP+ users that belong to the same MailUp list of a specified account

ListUserInfo

DescriptionThis method returns the list of SMTP+ users associated to the MailUp list of a specified account. Also the status details of each account are provided
HTTP MethodPOST
URLhttps://send.mailup.com/API/v2.0/users/listuserinfo 
Reference
 Click here to learn more about request parameters
The request must contain the user's credentials and an optional username to query

 

ListUsersDTO
ParameterTypeDescription
UserSMTPUserDTOthe calling User
UsernameStringoptional User from which to read the profile, if omitted the method returns the whole list of users

See the SendMessage reference for the definition of SMTPUserDTO

 

 Click here to learn more about response parameters

The response is given by a JSON or XML document that has the structure of a list of users informations ( List<UserInfoDTO>).

 

UserInfoDTO
ParameterTypeDescription
UsernameSMTPUserDTOthe username
IdConsolelongthe console ID
IdListlongthe list Id
IsEnabledbooltrue if the user is enabled
Priorityintthe priority
Notestringnote
CreationDatedatetimecreation date
UpdateDatedatetimelast update date
DomainListstringthe list of allowed domains
SenderListstringthe list of allowed sender
BlockUntildatetimethe date until the user is blocked
AdminBlockbooltrue if the user is blocked by the system administrator
JSON request (example)
{"User":{"Username":"sNNNN_NN","Secret":"..."},"Username":"sMMMM_MM"}
JSON response (example)

Example of a successful response:

{
"Status":"done",
"Code":"0",
"Message":"Ok",
"UserList":
[
{
"Username":"sMMMM_MM",
"IdConsole":123,
"IdList":1,
"IsEnabled":true,
"Priority":3,
"Note":"",
"CreationDate":"2015-03-31T12:12:04",
"UpdateDate":"2015-03-31T12:12:34",
"DomainList":"",
"SenderList":"",
"BlockUntil":"0001-01-01T00:00:00",
"AdminBlock":false
}
]
}

 

Example of error:

{
"Status":"error",
"Code":"112",
"Message":"User is deleted."
}

 

 


Error codes

This table shows possible HTTP response statuses that can be returned by the API methods and the corresponding error code provided by the application (inside the response).

HTTP response code
Application Code
Description
2000Ok
4001The operation is failed.
403101The input is null.
403102The operation is not authorized.
403103The user is not enabled.
403104The user is blocked.
403105The user is blocked until this date.
403106The console account is not found.
403107The console account is suspended.
403108The console account is deleted.
403109At least one recipient is required.
403110The sender is mandatory.
403111The template is not found.
403112User is deleted.

 

 

 

 

 

 

 

 

 

 

 

 

 

 


 

  • No labels