All Collections
API
General
How to manage custom headers
How to manage custom headers

Learn how to add Custom Headers in your emails.

Support Team avatar
Written by Support Team
Updated over a week ago

Custom headers are a great solution if you want to send debug info or any data you want along with the given email.
If you would like to add custom headers to your email you can do so by defining request parameters prefixed by headers_, like 'headers_customheader1', and by setting its value following a convention: 'customheader1: sometext'.
Note: space is required after the colon and before the custom header value!
For example: headers_comments=comments: This is a test"

Note: In order to pass Custom Headers in your emails please enable "Allow Custom Headers" option on your Settings screen.

cURL using SMTP protocol

curl --ssl-reqd \ 
--url 'smtps://smtp.elasticemail.com:2525' \
--user 'user@name.com:password' \
--mail-from 'verified@fromaddress.com' \
--mail-rcpt 'john@example.com' \
--upload-file mail.txt

mail.txt example

Date: Wed, 15 Dec 2021 12:45:55 -0700 
To: recipient@address.com
From: verified@fromaddress.com
Subject: UTF-8 MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Content-Type: text/html; charset="UTF-8"

Hello world,
Welcome to this example email

Custom PostBack header

You can also use this feature to send a postback header, which is a header that is returned in our system's notifications sent to you regarding your emails.

Example 1 - basic Postback header :

postback=This is a test

will result in a postback header

X-PostBack=This is a test

Example 2 - custom Postback header:

headers_postback-MyHeader=postback-MyHeader: value

will result in:

MyHeader=Value

using System;
using System.Collections.Specialized;
using System.Net;
using System.Text;

namespace ElasticEmailClient
{
    class Program
    {
        static void Main(string[] args)
        {
            NameValueCollection values = new NameValueCollection();
            values.Add("apikey", "00000000-0000-0000-0000-000000000000");
            values.Add("from", "youremail@yourdomain.com");
            values.Add("fromName", "Your Company Name");
            values.Add("to", "recipient1@gmail.com;recipient2@gmail.com");
            values.Add("subject", "Your Subject");
            values.Add("bodyText", "Text Body");
            values.Add("bodyHtml", "<h1>Html Body</h1>");
            values.Add("isTransactional", true);
            values.Add("headers_comments", "Comments: Let John know if you can see the emojis");
            values.Add("postback", "Just want this back if the email fails");

            string address = "https://api.elasticemail.com/v2/email/send";

            string response = Send(address, values);

            Console.WriteLine(response);
        }

        static string Send(string address, NameValueCollection values)
        {
            using (WebClient client = new WebClient())
            {
                try
                {
                    byte[] apiResponse = client.UploadValues(address, values);
                    return Encoding.UTF8.GetString(apiResponse);

                }
                catch (Exception ex)
                {
                    return "Exception caught: " + ex.Message + "\n" + ex.StackTrace;
                }
            }
        }

    }
}

JAVA

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStreamWriter;
import java.net.URL;
import java.net.URLConnection;
import java.net.URLEncoder;

public class ElasticEmailClient {
 
 public static String Send(String userName, String apiKey, String from, String fromName, String subject, String body, String to, String isTransactional) {
 
 try {
 
 String encoding = "UTF-8";
 
 String data = "apikey=" + URLEncoder.encode(apiKey, encoding);
 data += "&from=" + URLEncoder.encode(from, encoding);
 data += "&fromName=" + URLEncoder.encode(fromName, encoding);
 data += "&subject=" + URLEncoder.encode(subject, encoding);
 data += "&bodyHtml=" + URLEncoder.encode(body, encoding);
 data += "&to=" + URLEncoder.encode(to, encoding);
 data += "&isTransactional=" + URLEncoder.encode(isTransactional, encoding);
 
 URL url = new URL("https://api.elasticemail.com/v2/email/send");
 URLConnection conn = url.openConnection();
 conn.setDoOutput(true);
 OutputStreamWriter wr = new OutputStreamWriter(conn.getOutputStream());
 wr.write(data);
 wr.flush();
 BufferedReader rd = new BufferedReader(new InputStreamReader(conn.getInputStream()));
 String result = rd.readLine();
 wr.close();
 rd.close();

 return result;
 }
 
 catch(Exception e) {
 
 e.printStackTrace();
 }
 }

}

PHP

<?php
$url = 'https://api.elasticemail.com/v2/email/send';

try{
        $post = array('from' => 'youremail@yourdomain.com',
                      'fromName' => 'Your Company Name',
                      'apikey' => '00000000-0000-0000-0000-000000000000',
                      'subject' => 'Your Subject',
                      'to' => 'recipient1@gmail.com;recipient2@gmail.com',
                      'bodyHtml' => '&lt;h1&gt;Html Body&lt;/h1&gt;',
                      'bodyText' => 'Text Body',
                      'isTransactional' => false,
                      'headers_comments' => 'Comments: Let John know if you can see the emojis',
                      'postback' => 'Just want this back if the email fails');
       
        $ch = curl_init();
        curl_setopt_array($ch, array(
            CURLOPT_URL => $url,
            CURLOPT_POST => true,
            CURLOPT_POSTFIELDS => $post,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HEADER => false,
            CURLOPT_SSL_VERIFYPEER => false
        ));
       
        $result=curl_exec ($ch);
        curl_close ($ch);
       
        echo $result;    
}
catch(Exception $ex){
    echo $ex->getMessage();
}
?>

PHP without CURL

<?php

$url = 'https://api.elasticemail.com/v2/email/send';
$data = array('from' => 'youremail@yourdomain.com',
                      'fromName' => 'Your Company Name',
                      'apikey' => '00000000-0000-0000-0000-000000000000',
                      'subject' => 'Your Subject',
                      'to' => 'recipient1@gmail.com;recipient2@gmail.com',
                      'bodyHtml' => '&lt;h1&gt;Html Body&lt;/h1&gt;',
                      'bodyText' => 'Text Body',
                      'isTransactional' => false,
                      'headers_comments' => 'Comments: Let John know if you can see the emojis',
                      'postback' => 'Just want this back if the email fails');

// use key 'http' even if you send the request to https://...
$options = array(
    'http' => array(
        'header'  => "Content-type: application/x-www-form-urlencoded\r\n",
        'method'  => 'POST',
        'content' => http_build_query($data)
    )
);

$context  = stream_context_create($options);
$result = file_get_contents($url, false, $context);
if ($result === FALSE) { /* Handle error */ }

var_dump($result);

?>

Python

import requests
import json
from enum import Enum
class ApiClient:
    apiUri = 'https://api.elasticemail.com/v2'
    apiKey = '00000000-0000-0000-0000-0000000000000'

    def Request(method, url, data):
        data['apikey'] = ApiClient.apiKey
        if method == 'POST':
            result = requests.post(ApiClient.apiUri + url, params = data)
        elif method == 'PUT':
            result = requests.put(ApiClient.apiUri + url, params = data)
        elif method == 'GET':
            attach = ''
            for key in data:
                attach = attach + key + '=' + data[key] + '&'
            url = url + '?' + attach[:-1]
            result = requests.get(ApiClient.apiUri + url)    
           
        jsonMy = result.json()
       
        if jsonMy['success'] is False:
            return jsonMy['error']
           
        return jsonMy['data']

def Send(subject, EEfrom, fromName, to, bodyHtml, bodyText, isTransactional, customComment, postBack):
    return ApiClient.Request('POST', '/email/send', {
                'subject': subject,
                'from': EEfrom,
                'fromName': fromName,
                'to': to,
                'bodyHtml': bodyHtml,
                'bodyText': bodyText,
                'isTransactional': isTransactional,
                'headers_comments': customComment,
                'postback': postBack})
               
print(Send("Your Subject", "youremail@yourdomain.com", "Your Company Name", "&lt;h1&gt;Html Body&lt;/h1&gt;",
 "Text Body", True, "Comments: Let John know if you can see the emojis", "Just want this back if the email fails"))

License

All code samples are licensed under MIT license.

Did this answer your question?