SMTP Perl Code Example

Categories and Unique Arguments will be stored as a “Not PII” field and may be used for counting or other operations as SendGrid runs its systems. These fields generally cannot be redacted or removed. You should take care not to place PII in this field. SendGrid does not treat this data as PII, and its value may be visible to SendGrid employees, stored long-term, and may continue to be stored after you’ve left SendGrid’s platform.


# Version 1.0
# Last Updated 6/22/2009
use strict;
package SmtpApiHeader;
use JSON;

sub new
my $self = shift;
my @a = ();
$self = { 'data' => { }};
return $self;

sub addTo
my $self = shift;
my @to = @_;
push(@{$self->{data}->{to}}, @to);

sub addSubVal
my $self = shift;
my $var = shift;
my @val = @_;

if (!defined($self->{data}->{sub}->{$var}))
  $self->{data}->{sub}->{$var} = ();
push(@{$self->{data}->{sub}->{$var}}, @val);

sub setUniqueArgs
my $self = shift;
my $val = shift;
if (ref($val) eq 'HASH')
  $self->{data}->{unique_args} = $val;

sub setCategory
my $self = shift;
my $cat = shift;
$self->{data}->{category} = $cat;

sub addFilterSetting
my $self = shift;
my $filter = shift;
my $setting = shift;
my $val = shift;
if (!defined($self->{data}->{filters}->{$filter}))
  $self->{data}->{filters}->{$filter} = {};
if (!defined($self->{data}->{filters}->{$filter}->{settings}))
  $self->{data}->{filters}->{$filter}->{settings} = {};
$self->{data}->{filters}->{$filter}->{settings}->{$setting} = $val;

sub asJSON
my $self = shift;
my $json = JSON->new;
return $json->encode($self->{data});

sub as_string
my $self = shift;
my $json = $self->asJSON;
$json =~ s/(.{1,72})(\s)/$1\n   /g;
my $str = "X-SMTPAPI: $json";
return $str;

Example Perl Usage

use SmtpApiHeader;

my @receiver = ('kyle','bob','someguy');

my $hdr = SmtpApiHeader->new;

my $time = '1pm';
my $name = 'kyle';

$hdr->addFilterSetting('subscriptiontrack', 'enable', 1);
$hdr->addFilterSetting('twitter', 'enable', 1); #please check the apps available for your current package at

$hdr->addSubVal('-time-', $time);

$hdr->addSubVal('-name-', $time);
$hdr->setUniqueArgs({'test'=>1, 'foo'=>2});

print $hdr->as_string;

print "\n";

##  Full Perl Example
 <p>The following code builds a MIME mail message demonstrating all the portions of the SMTP API protocol. To use this example, you will need to have the following perl modules installed:</p>
<ul class="regular">
use strict;
use SmtpApiHeader;
use MIME::Entity;
use Net::SMTP;

my $hdr = SmtpApiHeader->new;

# The list of addresses this message will be sent to
my @toList = ('isaac@example', 'tim@example', 'jose@example');

# The names of the recipients
my @nameList = ('Isaac', 'Tim', 'Jose');

# Another substitution variable
my @timeList = ('4pm', '1pm', '2pm');

# Set all of the above variables
$hdr->addSubVal('-name-', @nameList);
$hdr->addSubVal('-time-', @timeList);

# Specify that this is an initial contact message

# Enable a text footer and set it
$hdr->addFilterSetting('footer', 'enable', 1);
$hdr->addFilterSetting('footer', "text/plain", "Thank you for your business");

my $from = '';

# For multiple recipient emails, the 'to' address is irrelevant
my $to = '';
my $plain = <<EOM;
Hello -name-,

Thank you for your interest in our products. We have set up an appointment
to call you at -time- EST to discuss your needs in more detail.


my $html = <<EOM;
<p>Hello -name-,<br />
 Thank you for your interest in our products. We have set up an appointment<br />
 to call you at -time- EST to discuss your needs in more detail.<br />

  Regards,<br />
  Fred<br />

# Create the MIME message that will be sent. Check out MIME::Entity on CPAN for more details
my $mime = MIME::Entity->build(Type  => 'multipart/alternative' ,

Encoding => '-SUGGEST',
From => $from,
To => $to,
Subject => 'Contact Response for <name> at <time>');

# Add the header
$mime->head->add("X-SMTPAPI", $hdr->asJSON);

# Add body
$mime->attach(Type => 'text/plain',
                  Encoding =>'-SUGGEST',
                  Data => $plain);

$mime->attach(Type => 'text/html',
                  Encoding =>'-SUGGEST',
                  Data => $html);

# Login credentials
my $username = 'apikey';
my $api_key = "your_api_key";

# Open a connection to the SendGrid mail server
my $smtp = Net::SMTP->new('',
                  Port=> 587,
                  Timeout => 20,
                  Hello => "");

# Authenticate
$smtp->auth($username, $api_key);

# Send the rest of the SMTP stuff to the server
Rate this page:

Need some help?

We all do sometimes. Get help now from the Twilio SendGrid Support Team.

Running into a coding hurdle? Lean on the wisdom of the crowd by browsing the SendGrid tag on Stack Overflow or visiting Twilio's Stack Overflow Collective.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!

Refer us and get $10 in 3 simple steps!

Step 1

Get link

Get a free personal referral link here

Step 2

Give $10

Your user signs up and upgrade using link

Step 3

Get $10

1,250 free SMSes
OR 1,000 free voice mins
OR 12,000 chats
OR more