Problem
How do I send an email using the outMail API in C# .NET?
How do I send an email in C# .NET with a RESTful API?
Solution
Below we will demonstrate on how to send an email from within your own csharp (C#) application. This is done by generating a RESTful API call to the outMail API service using the endpoint /email/send. Once outmail accepts the API call internally the message (email) is placed on the outMail SMTP (Simple Message Transfer Protocol) queue for sending. All messages (emails) will appear in the outMail stats and logs section of the management portal for the specified outMail account.
In layman's terms, you generate the email in your application and send it us using a RESTful API call and we do the rest and send the email onward.
outMail is an outgoing email server that supports the sending of emails either by SMTP or HTTP RESTful API calls.
The following example of code assumes you have already got a fully functional development environment, and you have working knowledge of C# and the .NET Libraries.
In your Visual Studio (VS) Solution you will need to add the NuGet package Newtonsoft.JSON.
Example code outmail-send.cs (below) was created from a blank .net core c# template with the Newtonsoft.JSON NuGet package added.
/**
* outmail-send.cs
*
*/
using Newtonsoft.Json;
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
namespace outmail_send
{
class Program
{
private const string apiSecretKey = "YOUR_SECRET_API_KEY";
private const string apiUrl = "https://api.smtp-engine.com/outmail/v1/email/send";
static void Main(string[] args)
{
List<string> toAddress = new List<string>();
toAddress.Add("someone@example.com");
toAddress.Add("someone-else@example.com");
// Create the new Email Message
Dictionary<string, object> newMessage = new Dictionary<string, object>();
newMessage.Add("api_key", apiSecretKey);
newMessage.Add("to", toAddress);
newMessage.Add("sender", "me@example.com");
newMessage.Add("subject", "Sending via Outmail API");
newMessage.Add("text_body", "This is the text message body");
newMessage.Add("html_body", "<body><h1>This is the HTML message</h1></body>");
// Convert the Dictionary to Json
string newMessageJsonStr = JsonConvert.SerializeObject(newMessage, Formatting.Indented);
// Create HTTP resource
HttpClient outMail = new HttpClient();
// Add an Accept header for JSON format.
outMail.DefaultRequestHeaders.Add("ContentType", "application/json");
// Create the content
var content = new StringContent(newMessageJsonStr, Encoding.UTF8, "application/json");
// Do the POST
var response = outMail.PostAsync(apiUrl, content).Result;
// Check the result for a valid HTTP 200 success and process the returned result
// or handler the failure.
if (response.IsSuccessStatusCode)
{
var jsonResponseStr = response.Content.ReadAsStringAsync().Result;
dynamic jsonResponse = JsonConvert.DeserializeObject(jsonResponseStr);
if (jsonResponse.ContainsKey("data"))
{
Console.WriteLine("status = {0}", jsonResponse["status"]);
Console.WriteLine("Message id = {0}", jsonResponse["data"]["email_id"]);
}
else
{
Console.WriteLine("response = {0}", response);
Console.WriteLine("json response = {0}", jsonResponse);
}
}
else
{
// Get the Json Error response and convert it
var jsonResponseStr = response.Content.ReadAsStringAsync().Result;
dynamic jsonResponse = JsonConvert.DeserializeObject(jsonResponseStr);
Console.WriteLine("status = {0}", jsonResponse["status"]);
Console.WriteLine("message = {0}", jsonResponse["message"]);
Console.WriteLine("error = {0}", jsonResponse["errors"]);
Console.WriteLine("{0} ({1})", (int)response.StatusCode, response.ReasonPhrase);
}
//Dispose once all HttpClient calls are complete.
outMail.Dispose();
}
}
}
Break down of the above code
The above code sends an email using a single RESTful API call to the endpoint /email/send. Documentation on this end point can be found here -> https://apidocs.smtp-engine.com/outmail/v1/#/
When sending emails via SMTP, outMail uses a username and password for SMTP authentication, however with the outMail API the authentication is done using a secret API key. If you haven't already got a API key you will need to generate a key in the management portal for outMail. This is done by going to the settings page of the desired outMail and clicking "Create API Key" in the "API Keys" section of the page.
The email message
The message is constructed using a C# Dictionary (newMessage) of type string and object. With in that dictionary we can construct the To Address, From Address, Subject and message content in both Text format and HTML format.
As with all messages; you can have multiple "To" email-addresses so this is set using a additional C# List (toAddress) of type string.
Once the newMessage has been constructed it is simply serialised into a JSON object and then used in a HTTP POST request to the outMail API endpoint URL.
If the email was successful you will receive a HTTP 200 OK status back, and the message will also appear in the outMail stats and SMTP logs sections with in the management portal.
Summary of server details
|
Outgoing server |
mxXXXXXX.smtp-engine.com As provided in your signup email. |
|
Outgoing server protocol |
SMTP |
|
Outgoing server port |
25, 465, 587, 2525 or 8025 |
|
Authentication Type |
Basic Authentication, SSL and TLS supported |
|
Username |
As provided |
|
Password |
As provided |
