Sending an email message
Example of json data for a request:
{
"from_email":"alice@example.org",
"from_name": "Alice",
"to": "bob@example.org",
"subject": "Hello",
"text": "Hello, Bob!",
"html": "<h1>Hello, Bob!</h1>",
"payment": "credit",
"smtp_headers": {
"Client-Id": "123"
}
}
An example of the request itself could look like this:
curl -X POST https://api.msndr.net/v1/email/messages \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Uses POST method and /email/messages
Successful responce
{
"id":1,
"from_email":"alice@example.org",
"from_name":"Alice",
"to":"bob@example.org",
"subject":"Hello",
"text":"Hello, Bob!",
"html":"<h1>Hello, Bob!</h1>",
"attachments": [],
"status":"queued",
"events": {
"open": 1,
"redirect": {
"http://foo.com": 2,
"http://bar.com": 3
},
"spam": 1,
"unsubscribe": 1
}
}
You can also send a message with attachments. Here is an example of how to do so:
curl -X POST https://api.msndr.net/v1/email/messages \
-H 'Authorization: Bearer $API_TOKEN' \
-F from_email=from@example.com \
-F to=to@example.com \
-F subject='Mail with attachments' \
-F text='Hello world' \
-F attachments[]=@/path/to/file1 \
-F attachments[]=@/path/to/file2 \
-F smtp_headers[Client-Id]=123
The following parameters are required: from_email, to, and subject. The optional parameters include from_name and text/html. Attachments are only supported for multipart/form-data content type requests and are stored as an array.
Payment is a way of rating the message. It can take the values:
1.subscriber_priority
2.credit_priority
3.subscriber
4.credit
If you don't specify a value, it will be subscriber_priority by default.
smtp_headers is a list of headers to be sent with the smtp message.
There are four ways to charge for messages:
subscriber_priority - Charge per subscriber. If there are no subscribers available, the charge will be per email. If no emails are available, an error will be returned.
credit_priority - Charge per letter. If no subscribers are available, the charge will be based on the number of letters. If no letters are available, an error will occur.
Subscriber - Charge per subscription. If no subscriptions are available, an error will occur.
Credit - Charge per credit. If no credits are available, an error occurs.
Here are some details about the server's JSON response to a single email request:
All parameters and their explanations are listed below:
Attribute |
Description |
id |
Message identifier |
from_email |
Email address of the sender |
from_name |
Name of the sender |
to |
Recipient's email address |
subject |
Subject of the message |
text |
Text version of the message |
html |
Html version of the message |
attachments |
Array of attached filenames |
status |
Status of the message |
events |
Information about occurred events |
There are six message statuses:
Queued - the message has been added to the queue
Sent - the message has been successfully sent and is waiting for delivery confirmation.
Delivered - the message has been delivered
Skipped - the message has not been sent. The recipient has opted out of receiving your messages or has been added to a problem list.
Soft_bounced - the message failed to be delivered. The recipient has temporarily bounced your message.
hard_bounced - there was an error while trying to deliver the message.
You can also get some information about the message that was sent.
To do this, you will need to run a query:
curl -X GET https://api.msndr.net/v1/email/messages/1 \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Uses the GET method and /email/messages/:id
where ID is the identification number of the message returned by the server in the above response.
Successful responce
{
"id":1,
"from_email":"alice@example.org",
"from_name":"Alice",
"to":"bob@example.org",
"subject":"Hello",
"text":"Hello, Bob!",
"html":"<h1>Hello, Bob!</h1>",
"status":"queued",
"events": {
"open": 1,
"redirect": {
"http://foo.com": 2,
"http://bar.com": 3
},
"spam": 1,
"unsubscribe": 1
}
}
attributes of the Json response from the server:
Id - message ID
from_email - sender's email address
from_name - sender's name
to - email address of the recipient
subject - message subject
text - text version of the message
html - html version of the message
status - message status
events - information about events related to this message.
Here are the possible message statuses:
Status |
Description |
queued |
The message has been accepted in the queue |
sent |
The message has been successfully sent |
delivered |
The message has been delivered to the recipient |
skipped |
The delivery of the message has been skipped |
soft_bounced |
The recipient's mail server rejected the message but it can be resent later |
hard_bounced |
The message cannot be delivered and the delivery has failed. |
Events that occur in response to such requests:
Event |
Description |
open |
The message is read |
redirect |
The recipient has clicked on the link |
spam |
Message is marked as spam |
unsubscribe |
User has unsubscribed |
Sending a message based on a given template
First of all, you will need to create a template. To do this, in your personal account in the Automation section, select Single by template and create a message template. You can send emails according to this template with parameters. To do this, you need to substitute the necessary parameters in the template using the [%parameter name%] construct. For example like this:
[%name%], [%age%], etc.
Example of json data for such a request:
{
"to": "bob@example.org",
"payment": "credit",
"params": {
"name": "Ivan",
"age": "33"
}
}
An example of the query itself:
curl -X POST https://api.msndr.net/v1/email/templates/1/messages \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer $API_TOKEN' \
-d '...JSON...'
Uses POST method and /email/templates/:template_id/messages
where template_id is the identification number of the template created in your personal account.
The request can take the following parameters:
Parameters |
Description |
Required |
to |
Email of the recipient |
Yes |
params |
Substitution parameters |
No |
payment |
The method of message tariffication. Possible values: |