This document outlines common ways our customers use Bird for general integration.  These integrations cover essential topics like “how do I send email?” and “how do I know what happened to the email?”  If you are transitioning from Postfix, Sendmail, or Exim, this document should explain everything you need to know about the basics of sending and reporting on email.  The rest of this document assumes you have an existing SparkPost account.

How do I send email?

Bird will accept mail for transfer in a couple of ways. By far, the most common is SMTP (Simple Mail Transfer Protocol) and Bird presents itself precisely as any other secure email agent on port 587. If you currently have generation or mail merge software that creates an email for delivery, Bird will accept it as a standard SMTP message and attempt to deliver it. You will need a system that with a valid TLS certificate that can generate SMTP messages and send them over port 587. Postfix, Sendmail, and Exim all have this capability natively.

Example 1:

You have a web server that generates a merged message for email delivery through Postfix.
· Adjust the web server’s generation software to send SMTP message to your assigned SparkPost server instead of the Postfix server
· Yes it really is that easy

Example 2:

You have some management code that needs to use the local server’s “Mail” function.
· If you are using Sendmail, edit the /etc/mail/sendmail.mc file to add a “smart-host” definition.
IE: define(`SMART_HOST’,`smtp.MyMessageBirdServer.com’)
· If you are using Postfix, edit the /etc/postfix/transport file to add an smtp relay definition.
IE: * smtp:MyMessageBirdServer.com
· Make sure you enable TLS and set your outbound port to 587.
· Apply the changes and restart the local mail services
· Execute the management code as, and the mail will route to MessageBird for delivery

What about REST injection?

For customers who use HTTP(S) to transport data in their networks, converting a message to SMTP can be cumbersome. Bird has a comprehensive REST API that can accept a JSON template, list of recipients, and substitution data over HTTPS and then convert that into generated (merged) email to be sent to the world over standard SMTP. This is particularly helpful to off-load the generation work from web servers to the mail engine.

Example:

Your servers generate a newsletter to 50,000 recipients daily merging personal data then send each individually through Postfix.
· Create JSON objects for the recipients, substitution data, and content template.
· Use the REST API to POST the JSON objects to Bird’s Transmission API. Doing this offloads the generation process to SparkPost for faster delivery.
· You can even put the JSON in a file and use cURL:

curl -v -H "Content-Type: application/json" -X POST \ https://api.bird.com/api/v1transmissions -d@./newsletter.json

How do I get delivery information?

Bird collects copious amounts of delivery information and makes that available to you in JSON format that can be “pushed” as a webhook or “pulled” with an API call. The data for a delivery looks something like this:

{      "campaign_id":"Welcome_Letter",    "customer_id":"108",    "delv_method":"esmtp",    "event_id":"84769964978165188",    "friendly_from":"bounce@sp-send.com",    "ip_address":"50.116.50.117",    "ip_pool":"default",    "message_id":"00046a82565a6d39451a",    "msg_from":"abc-bounces-108@sp-send..com",    "msg_size":"2164",    "num_retries":"0",    "queue_time":"1759",    "raw_rcpt_to":"fakespark+32@deadboltemail.com",    "rcpt_meta":{      },    "rcpt_tags":[      ],    "rcpt_to":"fakespark+32@deadboltemail.com",    "routing_domain":"deadboltemail.com",    "sending_ip":"52.38.47.118",    "subject":"Welcome Letter Template",    "tdate":"2018-01-10T21:15:24.000Z",    "template_id":"welcome-letter",    "template_version":"5",    "transmission_id":"84769964922735103",    "type":"delivery",    "timestamp":"2018-01-10T14:15:24.000-07:00" }

That is probably much more data than you are used to seeing in a Postfix log and it is already in a format that is easily consumable. It is relatively trivial to convert that JSON data to Postfix logging format if needed. Delivery, bounce, reject, spam_complaint, open, click, and delay data can be read the same way.

Examples:

1) You usually export Postfix logs out to Excel so you can sort and analyze.
A) Execute a message_events API call and run the resulting JSON data through JSON2CSV.

2) You like to convert your Postfix logs to JSON, then pull them into a web service for reading and analysis.
A) Use the MessageBird metrics API to poll SparkPost for the data you need, and it is automatically exported as JSON

3) You have a separate process that tails and parses the logs in real-time and updates a separate recipient database.
A) SparkPost can provide a real-time webhook that can feed your process spam_complaintants and unsubscribes specifically for this purpose. Implementation is trivial.

-Tom