NAV Navbar
shell
  • What is Flute Mail?
  • Authentication
  • POST /email
  • GET /email
  • Entity Types
  • What is Flute Mail?

    Flute Mail is a better email API that improves the delivery and reliability of your API-based email.

    It allows you to configure and use multiple email APIs such as SendGrid, Postmark, SparkPost, or any SMTP server, while maintaining your own logs and stats.

    We also invented Smart Failover. That means if we detect provider-caused spam bounces (such as this), we will automatically send through other configured providers, ensuring much better IP reliability than any single email provider can ever give you. Also, if a provider ever goes down or experiences delays (it happens surprisingly often) we automatically route your requests to another provider that you've configured.

    For more info about how Flute Mail can improve your deliverability, reliability and email ROI, read our technical whitepaper.







    What is a Virtual Flute?

    A Virtual Flute is a unique email account. Each Virtual Flute comes with its own API credentials and logs. You might have seperate flutes for different types of transactional emails that you regularly send, such as reminders, receipts, developer notifications, etc. This makes it easier to search, route, analyze, and improve the deliverability of your email.

    A Virtual Flute has 3 key components:

    Note the "From" address of the email sent is determined by the attached providers, not by the flute itself. So multiple emails sent from the same flute may appear to come from different "From" addresses. This is an intentional feature, which gives you powerful delivery-optimization features you wouldn't be able to get with a hard-coded "From".

    Example

    A small company might have 4 virtual flutes:

    Best practices

    Guideline 1: High granularity

    Generally speaking, the more flutes you have for different kinds of transactional email, the better. There is virtually no limit to how many flutes you can create. Sending different types of email through different flutes makes it easier to isolate issues and follow-up on logs later. It also makes it easier to unsubscribe users from certain types of emails, without blocking critical ones.

    The most important question to ask: is this email "critical" (such as a password reset or a monthly report) or of a "promotional" nature (like engagement notifications). These types of emails should be in seperate flutes so that you can control the deliverability/reputation of each seperately.

    Guideline 2: Have a redundant Smart Failover provider

    Always configure your flute to have a redundant "Smart Failover" provider, so that if requests fail through the primary provider (for whatever reason), your emails still get delivered.

    Guideline 3: Consider having your Smart Failover provider on a different domain

    Having your redundant provider on a different domain helps to protect against random domain reputation issues. For example you might send from yourcompany.com and yourcompanymail.com. Most businesses have multiple domains for different purposes (testing, etc.).

    Have an expert take a look.

    We're happy to assist users in designing and implementing a solid flute-y email strategy. Contact us for more info.










    Authentication

    Your API endpoint is https://$SUBDOMAIN.api.flutemail.com/v1/. Note the subdomain is unique to each customer.

    Every API request must be authenticated with a username and password. The username is your Virtual Flute username and the password is an API key for that flute. These keys can be generated from your Flute Mail dashboard.

    Different flutes must use different API keys. A key may only be viewed once, so save your keys in a credentials config file, and design your code so that it can use different username/key pairs for different types of email.

    Web API Authentication

    $ curl -v -u user:password my_subdomain.api.flutemail.com
    ...
    > Authorization: Basic dXNlcjpwYXNzd29yZA==
    ...
    

    SMTP API Authentication

    You may also use our SMTP relay to send email through a Virtual Flute. However please note that the web API is preferred whenever possible, as SMTP is a significantly slower protocol.










    POST /email

    POST https://$SUBDOMAIN.api.flutemail.com/v1/email

    Send an email.

    Example: Send a basic email

    export SUBDOMAIN="my_subdomain";
    export VFLUTE_USERNAME="my_virtual_flute_username";
    export VFLUTE_PASS="my_virtual_flute_API_key";
    export EMAIL_DEST="you@example.com";
    
    curl -X POST \
      https://$SUBDOMAIN.api.flutemail.com/v1/email \
      --user $VFLUTE_USERNAME:$VFLUTE_PASS \
      --header 'Content-Type: application/json' \
      --data '{
        "to": [{"email": "'$EMAIL_DEST'"}],
        "subject": "rumi says",
        "text": "listen to the song of the reed flute"
    }'
    

    You should get a JSON response that looks like this:

    {
        "status": "success",
        "data": {
            "id": "email-xxxxxxxxxxxxx"
        }
    }
    

    Let's send a very simple plaintext email.

    Variables:

    You don't need to specify a FROM address because this is defined by your Virtual Flute's providers.

    Headers

    Body Parameters

    Parameter Default Description
    subject required A non-empty string for the email's subject.
    to required An array of objects of {"name": "", "email": ""}. At least one must be provided.
    text '' A string for the text content of the email.
    html '' A string for the HTML content of the email.
    cc [] An array of objects of {"name": "", "email": ""}, same as the to parameter. Emails will be sent to these addresses, and they will be listed under the CC header.
    bcc [] An array of objects of {"name": "", "email": ""}, same as the to parameter. Emails will be sent to these addresses, but their email addresses will not be visible to other recipients.
    attachments [] An array of objects of {name, type, data}. See below for specification.
    images [] An array of objects of {name, type, data}. This is for inline images. See below for specification.
    reply_to '' A valid email address for the Reply-To header.
    headers {} Key-value pairing for any other SMTP headers. Headers such as Subject, From, To, CC and Reply-To will be overwritten and will not be allowed here.

    API Limitations

    Response

    A response looks like this:

    {
        "status": "success",
        "data": {
            "id": "xxxx-xxxx-xxxx"
        }
    }
    

    The id field in the response is your Flute Mail Email ID. This is a permanent reference to this request.

    Status fields

    Status Description
    success The email was successfully queued and logged. The ID of the email is in data/id.
    fail One or more inputs was invalid. The status code is between 400 and 499, and the error message is in data/message.
    error Internal server error. The status code is 500 or greater, and the error message is in message.

    Status codes can be one of the following:

    Code Description
    200 Successfully queued the email.
    400 One or more inputs are badly formed.
    401 Virtual Flute not found, does not have providers configured or access token is invalid.
    403 Access token was not specified.
    413 Payload is too large (exceeds 6 MB)
    415 Input is not in JSON format.
    422 One or more quotas exceeded
    500 Could not queue the email.

    Email Attachments

    Email attachments are simply JSON objects that look like this {"name": "filename.pdf", "type": "application/pdf", "data": "base64 encoded string"}

    Field Type Description
    name string, required The filename of the attachment, including extension. Maximum length is 255 bytes. For inline images, this must be unique, and it can be referred to in your HTML content using <img src="cid:'name'"/>.
    type string, required The MIME type of the attachment; e.g., text/plain, image/jpeg, application/pdf, etc.
    data string, required The content of the attachment as a Base64 encoded string. The string should not contain line breaks.




    GET /email

    Example: Retrieve an email

    export SUBDOMAIN="my_subdomain";
    export VFLUTE_USERNAME="my_virtual_flute_username";
    export VFLUTE_PASS="my_virtual_flute_API_key";
    export EMAIL_ID="email-xxxxxxxxxxxx";
    
    curl -X GET \
      https://$SUBDOMAIN.api.flutemail.com/v1/email/$EMAIL_ID \
      --user $VFLUTE_USERNAME:$VFLUTE_PASS \
      --header 'Content-Type: application/json' \
    

    You should get a JSON response that looks like this:

    {
        "status": "success",
        "data": {
            "id": "email-612a84c2781440c598debc9e3f28b1de",
            "requestStatus": "SUCCESS",
            "openStatus": "UNKNOWN",
            "createdAt": "2018-06-04T11:16:49.577Z",
            "updatedAt": "2018-06-04T11:18:24.473Z",
            "source": "API_OUT",
            "emailObject": {
                "from": {
                    "name": "Flute Mail SP Tester",
                    "email": "test@flutemail.io"
                },
                "to": [
                    {
                        "name": "Henry Pollock",
                        "email": "you@example.com"
                    }
                ],
                "subject": "this is the subject BANANA",
                "text": "this is the body text PEANUT BUTTER",
                "html": "this is the body html PARROT",
                "attachments": [],
                "images": [],
                "cc": [],
                "bcc": [],
                "headers": {
                    "X-Flute-Email-ID": "email-612a84c2781440c598debc9e3f28b1de"
                },
                "reply_to": ""
            }
        }
    }
    

    Let's retrieve an email we sent earlier.

    Variables:

    Query Parameters

    Parameter Default Description
    includeBody true If true, then emailObject will be added in the response body.
    includeRecipients false If true, then recipients will be added in the response body.

    See Entity Types for a description of the emailObject and recipients data.

    Status fields

    Status Description
    success The email was successfully retrieved.
    fail The email was not found.
    error Internal server error.

    Response Fields

    Field Description
    id Same as the parameter that was given.
    providersAttempted An array of provider objects. These are all of the providers that were attempted when trying to send the email.
    subject Email subject.
    requestStatus Either one of SUCCESS, FAIL, PENDING. SUCCESS means that the email was successfully sent through a provider. FAIL means all providers were attempted.
    createdAt The timestamp of when the request to send the email was received by our servers.
    updatedAt The last timestamp of when the email was modified in any way.
    errors An array of strings. If this is non-empty, the requestStatus should be FAIL.
    recipients An array of recipient objects. This is only provided if includeRecipients is true.
    emailObject The email object. This is only provided if includeBody is true

    Entity Types

    Recipients

    A recipient object looks like this:

    {
        "id": "1__EMAIL_ID",
        "to": "to@flutemail.com",
        "providerId": "xxxx-xxxx-xxxx",
        "providerMessageId": "xxxxxxxxxxxxx",
        "providerType": "provider",
        "requestStatus": "SUCCESS",
        "openStatus": "OPENED"
    }
    

    Emails

    An email body object looks like this:

    {
        "to": [
            {
                "name": "Name",
                "email": "email@flutemail.com"
            }
        ],
        "subject": "email subject",
        "text": "text content",
        "html": "html content",
        "attachments": [
            {
                "name": "file.jpg",
                "type": "image/jpeg",
                "data": "image data here"
            }
        ],
        "images": [
            {
                "name": "file.jpg",
                "type": "image/jpeg",
                "data": "image data here"
            }
        ],
        "cc": [
            {
                "name": "Name",
                "email": "email@flutemail.com"
            }
        ],
        "bcc": [
            {
                "name": "Name",
                "email": "email@flutemail.com"
            }
        ],
        "headers": {
            "X-Header": "header content"
        },
        "reply_to": "",
        "from": {
            "name": "Name",
            "email": "test@flutemail.com"
        }
    }
    

    All of these fields are identical to the ones received when the email object was first created (by the POST /v1/email endpoint)