Api reference MessageFlow
  • Welcome
  • Introduction
  • Authentication
  • REST clients samples
  • Long running actions - Retry-After header explained
  • Input compression
  • Using filters
  • Dynamic e-mail content
  • SMS Billing
  • Incoming webhooks
    • Steps to configure webhooks
    • Step 1: Identify the events to monitor
    • Step 2: Create a webhook endpoint
    • Step 3: Handle requests
    • Step 4: Test that your webhook
    • Step 4: Test your webhook
    • Step 5: Save your webhook configuration
  • External resources
  • Current Version
  • License
  • Groups
  • Contacts
  • Emails
  • Sms
  • Blacklist
  • Campaigns
  • Pushes
Powered by GitBook
On this page

Emails

PreviousContactsNextSms

Email API mainly allows you to send emails to all over the world. You can also create or delete email templates, get clicks, opens and statuses on your emails and more. * * There are two ways to send emails using our API: * - transactional email API that allows you to send emails to a single or an array of email addresses * - email campaigns that allows you to send emails to created group through API or account panel

Get template list

get

Use this method to list all created email templates.

Authorizations
Query parameters
offsetintegerOptional

The number of items omitted from the beginning of the list. Default ‘0’.

Default: 0
limitinteger · max: 1000Optional

The maximum number of items returned by request. Default ‘100’. Maximum ‘1000’.

Default: 100
smtpAccountstringOptional

The smtp account name.

Example: 1.test.smtp
externalIdstringOptional

The unique ID of the object you are looking for.

Responses
200
Request was successfully processed
application/json
401
Authorization data is invalid
application/json
404
Request was successfully processed but no results were returned
application/json
500
Request was not processed due to server error
application/json
get
using System.Threading.Tasks;

internal class Program
{
    private static void Main(string[] args)
    {
        string requestBody = "";

        try {
            using var client = new HttpClient{};
            using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.messageflow.com/v2.1/email/template?offset=0&limit=100&smtpAccount=1.test.smtp&externalId=<string>");

            request.Headers.Add("Authorization", "YourAuthorizationKey");
            request.Headers.Add("Application-Key", "YourApplicationKey");
            request.Content = new StringContent(requestBody, null, "application/json");

            var response = await client.SendAsync(request);
            response.EnsureSuccessStatusCode();
            string content = await response.Content.ReadAsStringAsync();
            Console.WriteLine(content);

        } catch (HttpRequestException e) {
            Console.WriteLine("\n Exception Caught!\n Message :{0} ", e.Message);
        }
    }
}
{
  "meta": {
    "numberOfErrors": 0,
    "numberOfData": 1,
    "status": 200,
    "uniqId": "00d928f759"
  },
  "data": [
    {
      "createdAt": "text",
      "html": "text",
      "text": "text",
      "name": "text",
      "externalId": "text",
      "smtpAccount": "text"
    }
  ]
}

Add template

post

Use this method to add email template which you can use with the Send emails method.

Authorizations
Body
htmlstringRequired

The HTML content of your message.

textstringRequired

The plain text content of your message.

namestringRequired

The name of the new template.

externalIdstringOptional

The unique ID of the new template. If you won’t add it the externalId will be generated in the response.

smtpAccountstringRequired

The name of your smtp account you want the new template to be saved on.

Responses
200
Request was successfully processed
application/json
207
Some of request body items were not processed due to validation errors
application/json
401
Authorization data is invalid
application/json
404
Request was successfully processed but no results were returned
application/json
500
Request was not processed due to server error
application/json
post
using System.Threading.Tasks;

internal class Program
{
    private static void Main(string[] args)
    {
        string requestBody = "{\"html\":\"\",\"text\":\"\",\"name\":\"\",\"externalId\":\"\",\"smtpAccount\":\"\"}";

        try {
            using var client = new HttpClient{};
            using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.messageflow.com/v2.1/email/template");

            request.Headers.Add("Authorization", "YourAuthorizationKey");
            request.Headers.Add("Application-Key", "YourApplicationKey");
            request.Content = new StringContent(requestBody, null, "application/json");

            var response = await client.SendAsync(request);
            response.EnsureSuccessStatusCode();
            string content = await response.Content.ReadAsStringAsync();
            Console.WriteLine(content);

        } catch (HttpRequestException e) {
            Console.WriteLine("\n Exception Caught!\n Message :{0} ", e.Message);
        }
    }
}
{
  "meta": {
    "numberOfErrors": 0,
    "numberOfData": 1,
    "status": 200,
    "uniqId": "00d928f759"
  }
}

Delete template

delete

Use this method to delete email templates.

Authorizations
Body
externalIdstring[]Required

The unique ID of the template.

Example: XXX-XXX
Responses
200
Request was successfully processed
application/json
207
Some of request body items were not processed due to validation errors
application/json
401
Authorization data is invalid
application/json
404
Request was successfully processed but no results were returned
application/json
500
Request was not processed due to server error
application/json
delete
using System.Threading.Tasks;

internal class Program
{
    private static void Main(string[] args)
    {
        string requestBody = "{\"externalId\":[\"XXX-XXX\"]}";

        try {
            using var client = new HttpClient{};
            using var request = new HttpRequestMessage(HttpMethod.Delete, "https://api.messageflow.com/v2.1/email/template");

            request.Headers.Add("Authorization", "YourAuthorizationKey");
            request.Headers.Add("Application-Key", "YourApplicationKey");
            request.Content = new StringContent(requestBody, null, "application/json");

            var response = await client.SendAsync(request);
            response.EnsureSuccessStatusCode();
            string content = await response.Content.ReadAsStringAsync();
            Console.WriteLine(content);

        } catch (HttpRequestException e) {
            Console.WriteLine("\n Exception Caught!\n Message :{0} ", e.Message);
        }
    }
}
{
  "meta": {
    "numberOfErrors": 0,
    "numberOfData": 1,
    "status": 200,
    "uniqId": "00d928f759"
  }
}

Get statistics

get

Use this method to get email statistics.

Authorizations
Query parameters
smtpAccountstringRequired

The name of your smtp account.

Example: 1.test.smtp
dateFromstringRequired

The start date of the range as timestamp.

dateTostringOptional

The end date of the range as timestamp.

withTagsintegerOptional

This field indicates whether the data should be aggregated by tags or not ( 1 - with aggregation, 0 - no aggregation ).

Example: 1
Responses
200
Request was successfully processed
application/json
207
Some of request body items were not processed due to validation errors
application/json
401
Authorization data is invalid
application/json
404
Request was successfully processed but no results were returned
application/json
500
Request was not processed due to server error
application/json
get
using System.Threading.Tasks;

internal class Program
{
    private static void Main(string[] args)
    {
        string requestBody = "";

        try {
            using var client = new HttpClient{};
            using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.messageflow.com/v2.1/email/aggregate?smtpAccount=1.test.smtp&dateFrom=<string>&dateTo=<string>&withTags=1");

            request.Headers.Add("Authorization", "YourAuthorizationKey");
            request.Headers.Add("Application-Key", "YourApplicationKey");
            request.Content = new StringContent(requestBody, null, "application/json");

            var response = await client.SendAsync(request);
            response.EnsureSuccessStatusCode();
            string content = await response.Content.ReadAsStringAsync();
            Console.WriteLine(content);

        } catch (HttpRequestException e) {
            Console.WriteLine("\n Exception Caught!\n Message :{0} ", e.Message);
        }
    }
}
{
  "meta": {
    "numberOfErrors": 0,
    "numberOfData": 1,
    "status": 200,
    "uniqId": "00d928f759"
  }
}

Get email clicks

get

Use this method to get details of clicks such as date, IP, browser, operation system and more. Please remember the clicks are stored for 7 days.

Authorizations
Query parameters
offsetintegerOptional

The number of items omitted from the beginning of the list. Default ‘0’.

Default: 0
limitinteger · max: 1000Optional

The maximum number of items returned by request. Default ‘100’. Maximum ‘1000’.

Default: 100
dateTostringOptional

Search with date. Use RFC 3339 standard or simpler "YYYY-MM-DD hh:mm:ii" format. The difference between dateTo and dateFrom cannot be more than 3 days.

Example: 2025-01-03 00:00:00
dateFromstringOptional

Search with date. Use RFC 3339 standard or simpler "YYYY-MM-DD hh:mm:ii" format. The difference between dateTo and dateFrom cannot be more than 3 days.

Example: 2025-01-01 00:00:00
smtpAccountstringOptional

The smtp account name.

Example: 1.test.smtp
messageIdstringOptional

The unique ID of the message.

Example: test0001@domena.pl
Responses
200
Request was successfully processed
application/json
401
Authorization data is invalid
application/json
404
Request was successfully processed but no results were returned
application/json
500
Request was not processed due to server error
application/json
get
using System.Threading.Tasks;

internal class Program
{
    private static void Main(string[] args)
    {
        string requestBody = "";

        try {
            using var client = new HttpClient{};
            using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.messageflow.com/v2.1/email/click?offset=0&limit=100&dateTo=2025-01-03 00:00:00&dateFrom=2025-01-01 00:00:00&smtpAccount=1.test.smtp&messageId=test0001@domena.pl");

            request.Headers.Add("Authorization", "YourAuthorizationKey");
            request.Headers.Add("Application-Key", "YourApplicationKey");
            request.Content = new StringContent(requestBody, null, "application/json");

            var response = await client.SendAsync(request);
            response.EnsureSuccessStatusCode();
            string content = await response.Content.ReadAsStringAsync();
            Console.WriteLine(content);

        } catch (HttpRequestException e) {
            Console.WriteLine("\n Exception Caught!\n Message :{0} ", e.Message);
        }
    }
}
{
  "meta": {
    "numberOfErrors": 0,
    "numberOfData": 1,
    "status": 200,
    "uniqId": "00d928f759"
  },
  "data": [
    {
      "messageId": "text",
      "date": "text",
      "to": "text",
      "smtpAccount": "text",
      "ip": "text",
      "browser": "text",
      "os": "text",
      "userAgent": "text",
      "link": "text"
    }
  ]
}

Get email statuses

get

Use this method to get details of the email with statuses such as injected, ok, softbounce, hardbounce, spambounce, deffered and dropped. By default, you can only access data from the last week

Authorizations
Query parameters
offsetintegerOptional

The number of items omitted from the beginning of the list. Default ‘0’.

Default: 0
limitinteger · max: 1000Optional

The maximum number of items returned by request. Default ‘100’. Maximum ‘1000’.

Default: 100
smtpAccountstringOptional

The smtp account name.

Example: 1.test.smtp
messageIdstringOptional

The unique ID of the message.

Example: test0001@domena.pl
tostringOptional

The email address the email was sent to.

Example: test@email.pl
dateFromstringOptional

Search with date. Use RFC 3339 standard or simpler "YYYY-MM-DD hh:mm:ii" format. The farthest date is specified by the TTL of your account (which is 1 week by default).

Example: 2025-01-01 00:00:00
dateTostringOptional

Search with date. Use RFC 3339 standard or simpler "YYYY-MM-DD hh:mm:ii" format.

Example: 2025-01-03 00:00:00
Responses
200
Request was successfully processed
application/json
401
Authorization data is invalid
application/json
404
Request was successfully processed but no results were returned
application/json
500
Request was not processed due to server error
application/json
get
using System.Threading.Tasks;

internal class Program
{
    private static void Main(string[] args)
    {
        string requestBody = "";

        try {
            using var client = new HttpClient{};
            using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.messageflow.com/v2.1/email?offset=0&limit=100&smtpAccount=1.test.smtp&messageId=test0001@domena.pl&to=test@email.pl&dateFrom=2025-01-01 00:00:00&dateTo=2025-01-03 00:00:00");

            request.Headers.Add("Authorization", "YourAuthorizationKey");
            request.Headers.Add("Application-Key", "YourApplicationKey");
            request.Content = new StringContent(requestBody, null, "application/json");

            var response = await client.SendAsync(request);
            response.EnsureSuccessStatusCode();
            string content = await response.Content.ReadAsStringAsync();
            Console.WriteLine(content);

        } catch (HttpRequestException e) {
            Console.WriteLine("\n Exception Caught!\n Message :{0} ", e.Message);
        }
    }
}
{
  "meta": {
    "numberOfErrors": 0,
    "numberOfData": 1,
    "status": 200,
    "uniqId": "00d928f759"
  },
  "data": [
    {
      "subject": "text",
      "smtpAccount": "1.test.smtp",
      "tags": [
        "text"
      ],
      "to": [
        {
          "email": "test@domena.pl",
          "name": "Test sender",
          "messageId": "test0001@domena.pl"
        }
      ],
      "from": {
        "email": "text",
        "name": "text"
      },
      "status": "text",
      "statusTime": 1,
      "statusDesc": "text",
      "allStatuses": [
        {
          "status": "text",
          "statusTime": 1,
          "statusDesc": "text"
        }
      ]
    }
  ]
}

Send emails

post

Send new email through transactional API which means that you can send email to a single email address or an array of email addresses. You can send the message to a maximum of 200 recipients. The entire query should not exceed 10 MB, and should not exceed 10 000 elements. If you want to send email to a group created through Create group method please use Send email campaign. Link tracking is enabled by default, you can disable it by adding a header {"X-TRACKING-OFF":1}

Authorizations
Body

Object passed when sending emails.

subjectstring · min: 2 · max: 128Required

The subject of the message.

Example: Test email subject
smtpAccountstringRequired

The smtp account name the email will be sent from.

Example: 1.test.smtp
tagsstring[]Optional

The values to tag the message with. Tags can be non-unique.

Example: test-tag
Responses
200
Request was successfully processed
application/json
207
Some of request body items were not processed due to validation errors
application/json
401
Authorization data is invalid
application/json
404
Request was successfully processed but no results were returned
application/json
500
Request was not processed due to server error
application/json
post
using System.Threading.Tasks;

internal class Program
{
    private static void Main(string[] args)
    {
        string requestBody = "{\"subject\":\"Test email subject\",\"smtpAccount\":\"1.test.smtp\",\"tags\":[\"test-tag\"],\"content\":[],\"bcc\":[[]],\"cc\":[[]],\"from\":[],\"replyTo\":[],\"headers\":{\"X-TEST-HEADER\":\"val\"},\"globalVars\":{\"sex\":\"unknown\",\"hasNewsletter\":false,\"promos\":{\"1\":{\"name\":\"test40\",\"value\":300},\"2\":{\"name\":\"test800\",\"value\":3008}},\"footer\":\"<div><strong>crazy footer<\\/strong><\\/div>\"},\"to\":[[]],\"attachments\":[[]]}";

        try {
            using var client = new HttpClient{};
            using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.messageflow.com/v2.1/email");

            request.Headers.Add("Authorization", "YourAuthorizationKey");
            request.Headers.Add("Application-Key", "YourApplicationKey");
            request.Content = new StringContent(requestBody, null, "application/json");

            var response = await client.SendAsync(request);
            response.EnsureSuccessStatusCode();
            string content = await response.Content.ReadAsStringAsync();
            Console.WriteLine(content);

        } catch (HttpRequestException e) {
            Console.WriteLine("\n Exception Caught!\n Message :{0} ", e.Message);
        }
    }
}
{
  "meta": {
    "numberOfErrors": 0,
    "numberOfData": 1,
    "status": 200,
    "uniqId": "00d928f759"
  },
  "data": [
    {
      "subject": "text",
      "smtpAccount": "1.test.smtp",
      "tags": [
        "text"
      ],
      "to": [
        {
          "email": "test@domena.pl",
          "name": "Test sender",
          "messageId": "test0001@domena.pl"
        }
      ],
      "from": {
        "email": "text",
        "name": "text"
      },
      "status": "text",
      "statusTime": 1,
      "statusDesc": "text",
      "allStatuses": [
        {
          "status": "text",
          "statusTime": 1,
          "statusDesc": "text"
        }
      ]
    }
  ]
}

Get email opens

get

Use this method to get details of email opens such as date, IP, browser, operation system and more. Please remember the opens are stored for 7 days.

Authorizations
Query parameters
offsetintegerOptional

The number of items omitted from the beginning of the list. Default ‘0’.

Default: 0
limitinteger · max: 1000Optional

The maximum number of items returned by request. Default ‘100’. Maximum ‘1000’.

Default: 100
dateTostringOptional

Search with date. Use RFC 3339 standard or simpler "YYYY-MM-DD hh:mm:ii" format. The difference between dateTo and dateFrom cannot be more than 3 days.

Example: 2025-01-03 00:00:00
dateFromstringOptional

Search with date. Use RFC 3339 standard or simpler "YYYY-MM-DD hh:mm:ii" format. The difference between dateTo and dateFrom cannot be more than 3 days.

Example: 2025-01-01 00:00:00
smtpAccountstringOptional

The smtp account name.

Example: 1.test.smtp
messageIdstringOptional

The unique ID of the message.

Example: test0001@domena.pl
Responses
200
Request was successfully processed
application/json
401
Authorization data is invalid
application/json
404
Request was successfully processed but no results were returned
application/json
500
Request was not processed due to server error
application/json
get
using System.Threading.Tasks;

internal class Program
{
    private static void Main(string[] args)
    {
        string requestBody = "";

        try {
            using var client = new HttpClient{};
            using var request = new HttpRequestMessage(HttpMethod.Get, "https://api.messageflow.com/v2.1/email/open?offset=0&limit=100&dateTo=2025-01-03 00:00:00&dateFrom=2025-01-01 00:00:00&smtpAccount=1.test.smtp&messageId=test0001@domena.pl");

            request.Headers.Add("Authorization", "YourAuthorizationKey");
            request.Headers.Add("Application-Key", "YourApplicationKey");
            request.Content = new StringContent(requestBody, null, "application/json");

            var response = await client.SendAsync(request);
            response.EnsureSuccessStatusCode();
            string content = await response.Content.ReadAsStringAsync();
            Console.WriteLine(content);

        } catch (HttpRequestException e) {
            Console.WriteLine("\n Exception Caught!\n Message :{0} ", e.Message);
        }
    }
}
{
  "meta": {
    "numberOfErrors": 0,
    "numberOfData": 1,
    "status": 200,
    "uniqId": "00d928f759"
  },
  "data": [
    {
      "messageId": "text",
      "date": "text",
      "to": "text",
      "smtpAccount": "text",
      "ip": "text",
      "browser": "text",
      "os": "text",
      "userAgent": "text"
    }
  ]
}

Get smtp account list

options

Use this method to list details of the smtp account such as smtp name, smtp type and vps connected to your account.

Authorizations
Responses
200
Request was successfully processed
application/json
401
Authorization data is invalid
application/json
404
Request was successfully processed but no results were returned
application/json
500
Request was not processed due to server error
application/json
options
using System.Threading.Tasks;

internal class Program
{
    private static void Main(string[] args)
    {
        string requestBody = "";

        try {
            using var client = new HttpClient{};
            using var request = new HttpRequestMessage(HttpMethod.Options, "https://api.messageflow.com/v2.1/email/smtpAccount");

            request.Headers.Add("Authorization", "YourAuthorizationKey");
            request.Headers.Add("Application-Key", "YourApplicationKey");
            request.Content = new StringContent(requestBody, null, "application/json");

            var response = await client.SendAsync(request);
            response.EnsureSuccessStatusCode();
            string content = await response.Content.ReadAsStringAsync();
            Console.WriteLine(content);

        } catch (HttpRequestException e) {
            Console.WriteLine("\n Exception Caught!\n Message :{0} ", e.Message);
        }
    }
}
{
  "meta": {
    "numberOfErrors": 0,
    "numberOfData": 1,
    "status": 200,
    "uniqId": "00d928f759"
  },
  "data": [
    {
      "smtpAccount": "text",
      "smtpName": "text",
      "smtpType": "text",
      "vps": [
        {
          "vpsName": "text",
          "host": "text",
          "vpsType": "text",
          "ip": "text"
        }
      ]
    }
  ]
}
  • GETGet template list
  • POSTAdd template
  • DELETEDelete template
  • GETGet statistics
  • GETGet email clicks
  • GETGet email statuses
  • POSTSend emails
  • GETGet email opens
  • OPTIONSGet smtp account list