Introduction

Welcome to the Legitmailer API! You can use our API to access Legitmailer API endpoints to send emails, manage templates and contact lists.

Authentication

Legitmailer uses API keys to allow access to the API. You can register a new Legitmailer API key at our website.

Legitmailer expects for the API key to be included in all API requests to the server in a header that looks like the following:

Authorization: Bearer ${API-KEY}

You must replace ${API-KEY} with your personal API key.

Send Email

Send email

This endpoint is to send transactional email without using any template.

Send an email using curl

curl -X POST \
  https://app.legitmailer.com/api/email \
  -H 'Authorization: Bearer ${API-KEY}' \
  -H 'Content-Type: application/json' \
  -d '{  "validate": "true",
 "fromAddress":"info@legitmailer.com",
 "toAddress":"contact@legitmailer.com",
 "subject":"hello",
 "body":"FYI",
  "contentType":"text/plain"
}'

The successfull response would return


{
  trackingId : "2lvekdFTHBXUk9VU0NhNkVZZG"
}

HTTP Request

POST https://app.legitmailer.com/api/email

Request Body

Parameter	Required	Default	Description
validate	No	false	Validates the email address before sending. This helps in maintaining the server reputation and avoid sending to email addresses which are undeliverable.
fromAddress	Yes		Email address of the sender
toAddress	Yes		Email address of the reciever
subject	Yes		Subject for the email
body	Yes		Message for the email
contentType	No	text/html	Choose text/plain if you want to send email as plain text

Response

The API will return the trackingId for the sent email which can be used to track the email.

Send email with template

This endpoint is to send transactional email using an existing template. Email templates can be created in the application.

HTTP Request

POST https://app.legitmailer.com/api/email/template

The tokenMap attributes to replace could be obtained by the view tab for the template


curl -X POST \
  https://app.legitmailer.com/api/email/template \
  -H 'Authorization: Bearer ${API-KEY}' \
  -H 'Content-Type: application/json' \
  -d '{  "validate": "false",
 "template":"welcome",
 "email":"contact@legitmailer.com",
 "tokenMap":{
  "name": "legitmailer"
 }

}'

The successfull response would return


{
  trackingId : "2lvekdFTHBXUk9VU0NhNkVZZG"
}

Request Body

Parameter	Required	Default	Description
validate	No	false	Validates the email address before sending. This helps in maintaining the server reputation and avoid sending to email addresses which are undeliverable.
template	Yes		Name of the template
email	Yes		Email address of the reciever
tokenMap	Yes		Map of all the token placeholders in the template with their substitution value

Response

The API will return the trackingId for the sent email which can be used to track the email.

Send bulk email

This end point is to send emails in bulk using template


curl -X POST \
  https://app.legitmailer.com/api/batch/email/template \
  -H 'Authorization: Bearer ${API-KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
  "validate": "true",
  "template": "registration",
  "emailList":[
    {
      "email": "contact@legitmailer.com",
      "tokenMap":{
       "username" :"legitmailer"
          }
    }
  ]
}'

HTTP Request

POST https://app.legitmailer.com/api/batch/email/template

Request Body

Parameter	Required	Default	Description
validate	No	false	Validates the email address before sending. This helps in maintaining the server reputation and avoid sending to email addresses which are undeliverable.
template	Yes		Name of the template
emailList	Yes		List of email addresses
emailList[*].tokenMap	Yes		Map of all the token placeholders in the template with their substitution value for the given email address

Delayed Email

At times we want to queue the email at some future time along with the ability to remove it from the queue if we need to do so. The delayed email API provides this feature which makes it simple to select a time in future when we want to send the email. If for some reasons anything changes we do have an option to cancel that unsent email.

Queue email

This end point is used to schedule an email without using template

Schedule to send an email after 5 minutes using curl

curl -X POST \
  https://app.legitmailer.com/api/email/delayed \
  -H 'Authorization: Bearer ${API-KEY}' \
  -H 'Content-Type: application/json' \
  -d '{  
        "validate": "true",
       "fromAddress":"info@legitmailer.com",
       "toAddress":"contact@legitmailer.com",
       "subject":"hello",
       "body":"FYI",
       "contentType":"text/plain",
       "delay":300
    }'

The successfull response would return


{
  requestId : "sdsds3sdf"
}

HTTP Request

POST https://app.legitmailer.com/api/email/delayed

Request Body

Parameter	Required	Default	Description
validate	No	false	Validates the email address before sending. This helps in maintaining the server reputation and avoid sending to email addresses which are undeliverable.
fromAddress	Yes		Email address of the sender
toAddress	Yes		Email address of the reciever
subject	Yes		Subject for the email
body	Yes		Message for the email
contentType	No	text/html	Choose text/plain if you want to send email as plain text
delay	Yes		Delay in minutes after which we want to schedule email

Response

Parameter	Description
requestId	Request Identifier, this can be used to cancel the delayed email if required

Queue email with template

This end point is used to schedule an email using a template

Schedule to send an email after 5 minutes using curl The tokenMap attributes to replace could be obtained by the view tab for the template


curl -X POST \
  https://app.legitmailer.com/api/email/template/delayed \
  -H 'Authorization: Bearer ${API-KEY}' \
  -H 'Content-Type: application/json' \
  -d '{  "validate": "false",
         "template":"welcome",
         "email":"contact@legitmailer.com",
         "delay":300
         "tokenMap":{
          "name": "legitmailer"
          }
      }'

The successfull response would return


{
  trackingId : "2lvekdFTHBXUk9VU0NhNkVZZG"
}

HTTP Request

POST https://app.legitmailer.com/api/email/template/delayed

Request Body

Parameter	Required	Default	Description
validate	No	false	Validates the email address before sending. This helps in maintaining the server reputation and avoid sending to email addresses which are undeliverable.
template	Yes		Name of the template
email	Yes		Email address of the reciever
tokenMap	Yes		Map of all the token placeholders in the template with their substitution value
delay	Yes		Delay in minutes after which we want to schedule email

Response

Parameter	Description
requestId	Request Identifier, this can be used to cancel the delayed email if required

Cancel Queued email

This end point deletes the queued email if it has not yet been sent

curl -X DELETE \
  https://app.legitmailer.com/api/email/delayed/uhjxzc788 \
  -H 'Authorization: Bearer ${API-KEY}' \
  -H 'Content-Type: application/json' \

HTTP Request

DELETE https://app.legitmailer.com/api/email/delayed/{requestId}

Path Variable

Parameter	Description
requestId	The unique identifier which is returned when the email is queued.

Response

The API return 204 if the queued email is successfully removed otherwise it throws 400

Templates

List Templates

Request for template list

curl -X GET \
  https://app.legitmailer.com/api/template/list \
  -H 'Authorization: Bearer ${API-KEY}' \
  -H 'Content-Type: application/json' \

Response body

{
    "count": 2,
    "templates": [
        {
            "name": "registration",
            "templateId": "cmVnaXN0cmF0aW9u"
        },
        {
            "name": "welcome",
            "templateId": "bXkgY2hvaWNjZSByZWdpc3RyYXRpb24="
        }
    ]
}

Retrieves list of all the templates for your account

HTTP Request

GET https://app.legitmailer.com/api/template/list

Response

The API returns list of all the templates with template name and templateId

Get Template Detail

Request for template detail

curl -X GET \
  https://app.legitmailer.com/api/template/cmVnaXN0cmF0aW9u \
  -H 'Authorization: Bearer ${API-KEY}' \
  -H 'Content-Type: application/json'

Response body

{
    "contentType": "text/html",
    "fromEmail": "contact@legitmailer.com",
    "name": "registration",
    "subject": "Welcome to legitmailer",
    "body": "<h3>hi ${username},</h3>\r\n<br/>\r\nWelcome to legitmailer. Discover new things\r\n<br/>\r\n\r\n\r\nBest,<br/>\r\nTeam Legitmailer",
    "tokens": [
        "username"
    ]
}

Retrieves detail for a template for the given templateId

HTTP Request

GET https://app.legitmailer.com/api/template/{templateId}

Path Variable

Parameter	Description
templateId	The unique identifier for the template which can be retrieved using template list API.

Response

Attribute	Description
contentType	Content type for the email template
fromEmail	From address configured in the template
name	Template Name
subject	Subject for the email configured for the template
body	Message body for the email configured for the template
tokens	List of all the placeholders configured in the email template

Contact List

The contact lists can be managed programatically using the API's.

Get Contact Lists

Request list of all the contact lists

curl -X GET \
  https://app.legitmailer.com/api/contactlist \
  -H 'Authorization: Bearer ${API-KEY}' \
  -H 'Content-Type: application/json'

Response body

{
    "count": 2,
    "contactLists": [
        {
            "name": "first",
            "description": "My first list",
            "size": 134,
            "createdOn": "2019-06-26T05:11:47.000+0000",
            "contactListId": "c2Rmc2Rmc2Rm"
        },
        {
            "name": "second",
            "description": "My second list",
            "size": 2,
            "createdOn": "2019-06-25T20:18:16.000+0000",
            "contactListId": "c2luZ2xl"
        }
    ]
}

The API returns list of all the contact lists for the account

HTTP Request

GET https://app.legitmailer.com/api/contactlist

Response

Attribute	Description
count	Number of contact lists
name	Name of the contact list
description	Description for the contact list
size	Number of contacts in the contact list
createdOn	Date for the creation of the contact list
contactListId	Unique identifier for the contact list

Add Contact

Add a contact to the list

curl -X POST \
  https://app.legitmailer.com/api/contactlist/c2Rmc2Rmc2Rm/contact/43223 \
  -H 'Authorization: Bearer ${API-KEY}' \
  -H 'Content-Type: application/json' 
  -d '{
  "email": "contact@legitmailer.com",
  "data":[
     {
      "name": "contact"
     }
  ]
}'

This API add a contact to existing contact list. The end point requires an unique identifier to be specified for the contact. It can be email or any other identifier that we want to associate with the contact record.

HTTP Method

POST https://app.legitmailer.com/api/contactlist/{contactListId}/contact/{customerId}

Path Variable

Parameter	Description
contactListId	The unique identifier for the contact list which can be retrieved using contact list API.
customerId	Unique identifier that we want to associate with the record. This is required to retrieve, modify the contact using API in future.

Request Body

Parameter	Required	Description
email	Yes	Email address for the contact
data	Yes	The key value pair for the columns defined for the given contact list. The column definitions are manageble with the application.

Get Contact

Fetch contact details

curl -X GET \
  https://app.legitmailer.com/api/contactlist/c2Rmc2Rmc2Rm/contact/43223 \
  -H 'Authorization: Bearer ${API-KEY}' \
  -H 'Content-Type: application/json'

Response Body

{
    "contactListName": "sdfsdfsdf",
    "customerId": "43223",
    "email": "contact@legitmailer.com",
    "data": [
     {
      "name": "contact"
     }
  ]
}

This API retrieves the contact from the list

HTTP Method

GET https://app.legitmailer.com/api/contactlist/{contactListId}/contact/{customerId}

Path Variable

Parameter	Description
contactListId	The unique identifier for the contact list which can be retrieved using contact list API.
customerId	Unique identifier which was assiciated with the contact record when the record was created.

Response Body

Parameter	Description
email	Email address for the contact
data	The key value pair for the columns defined for the given contact list. The column definitions are manageble with the application.
customerId	Unique identifier which was assiciated with the contact record when the record was created.
contactListName	Name of the contact list

Update Contact

curl -X PUT \
  https://app.legitmailer.com/api/contactlist/c2Rmc2Rmc2Rm/contact/43223 \
  -H 'Authorization: Bearer ${API-KEY}' \
  -H 'Content-Type: application/json'
  -d '{
  "email": "info@legitmailer.com",
  "data": [
     {
      "name": "info"
     }
}'

This API updates an existing contact

HTTP Method

PUT https://app.legitmailer.com/api/contactlist/{contactListId}/contact/{customerId}

Path Variable

Parameter	Description
contactListId	The unique identifier for the contact list which can be retrieved using contact list API.
customerId	Unique identifier which was assiciated with the contact record when the record was created.

Request Body

Parameter	Required	Description
email	Yes	Email address for the contact
data	Yes	The key value pair for the columns defined for the given contact list. The column definitions are manageble with the application.

Delete Contact

curl -X DELETE \
  https://app.legitmailer.com/api/contactlist/c2Rmc2Rmc2Rm/contact/43223 \
  -H 'Authorization: Bearer ${API-KEY}' \
  -H 'Content-Type: application/json'

This API deletes an existing contact with the given customerId

HTTP Method

DELETE https://app.legitmailer.com/api/contactlist/{contactListId}/contact/{customerId}

Path Variable

Parameter	Description
contactListId	The unique identifier for the contact list which can be retrieved using contact list API.
customerId	Unique identifier which was assiciated with the contact record when the record was created.

Errors

The Legitmailer API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
404	Not Found -- The specified kitten could not be found.
405	Method Not Allowed -- You tried to access a endpoint with an invalid method.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.