README
¶
This helper is a stand-alone module to help get you started consuming and processing Inbound Parse data.
Table of Contents
Fields
ParsedEmail.Envelope
ParsedEmail.Envelope.To and ParsedEmail.Envelope.From represent the exact email addresses that the email was sent to and the exact email address of the sender. There are no special characters and these fields are safe to use without further parsing as email addresses
ParsedEmail.ParsedValues
Please see SendGrid Docs to see what fields are available and preparsed by SendGrid. Use these fields over the Headers as they are parsed by SendGrid and gauranteed to be consistent
ParsedEmail.TextBody
this field will satisfy most cases. SendGrid pre-parses the body into a plain text string separated with \n
ParsedEmail.ParsedAttachments
populated only when processing the email with ParseWithAttachments(). Provides the following ease of use values
- File: full attachment for uploading or processing (see example to upload to s3)
- Size: file size, useful for filtering or setting upper limits to attachments
- Filename: copies the original filename of the attachment, if there is not one, it defaults to 'Untitled'
- ContentType: the type of file
ParsedEmail.Body
populated only when the raw option is checked in the SendGrid Dashboard. Provides the raw HTML body of the email, unless you need to record the exact unparsed HTML payload from the email client, you should use the parsed fields instead. The field is named Body for backward compatability
ParsedEmail.Attachments
populated only when the raw option is checked in the SendGrid Dashboard. This field is deprecated. Use ParsedAttachments instead which does not require the Raw setting, and provides parsed values to use and process the attachments
ParsedEmail.Headers
this field is deprecated. Use the SendGrid processed fields in ParsedValues instead. While it maintains its presence to avoid breaking changes, it provides raw, unprocessed headers and not all email clients are compatible. For example. these fields will be empty if the email cient is Outlook.com
Example Usage
package main
import (
"fmt"
"log"
"net/http"
"github.com/sendgrid/sendgrid-go/helpers/inbound"
)
func inboundHandler(response http.ResponseWriter, request *http.Request) {
parsedEmail, err := ParseWithAttachments(request)
if err != nil {
log.Fatal(err)
}
fmt.Print(parsedEmail.Envelope.From)
for filename, contents := range parsedEmail.ParsedAttachments {
// Do something with an attachment
handleAttachment(filename, contents)
}
for section, body := range strings.Split(parsedEmail.TextBody, "\n") {
// Do something with the email lines
}
// Twilio SendGrid needs a 200 OK response to stop POSTing
response.WriteHeader(http.StatusOK)
}
// example of uploading an attachment to s3 using the Go sdk-2
func handleAttachment(parsedEmail *ParsedEmail) {
for _, contents := range parsedEmail.ParsedAttachments {
if _, err := sgh.Client.Upload(ctx, &s3.PutObjectInput{
Bucket: &bucket,
Key: &uploadPath,
Body: contents.File,
ContentType: aws.String(contents.ContentType),
}
}
}
func main() {
http.HandleFunc("/inbound", inboundHandler)
if err := http.ListenAndServe(":8000", nil); err != nil {
log.Fatalln("Error")
}
}
Testing the Source Code
Tests are located in the helpers/inbound folder:
Learn about testing this code here.
Contributing
If you would like to contribute to this project, please see our contributing guide. Thanks!
Documentation
¶
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type EmailAttachment ¶
type EmailAttachment struct {
File multipart.File `json:"-"`
Filename string `json:"filename"`
Size int64 `json:"-"`
ContentType string `json:"type"`
}
EmailAttachment defines information related to an email attachment
type ParsedEmail ¶
type ParsedEmail struct {
// Header values are raw and not pre-processed by SendGrid. They may change depending on the email client. Use carefully
Headers map[string]string
// Please see https://docs.sendgrid.com/for-developers/parsing-email/setting-up-the-inbound-parse-webhook to see the available fields in the email headers
// all fields listed there are available within the headers map except for text which lives in the TextBody field
ParsedValues map[string]string
// Primary email body parsed with \n. A common approach is to Split by the \n to bring every line of the email into a string array
TextBody string
// Envelope expresses the exact email address that the email was addressed to and the exact email address it was from, without extra characters
Envelope struct {
From string `json:"from"`
To []string `json:"to"`
}
// Attachments have been fully parsed to include the filename, size, content type and actual file for uploading or processing
ParsedAttachments map[string]*EmailAttachment
// Raw only
Attachments map[string][]byte
// accessed with text/html and text/plain. text/plain is always parsed to the TextBody field
Body map[string]string
// contains filtered or unexported fields
}
ParsedEmail defines a multipart parsed email Body and Attachments are only populated if the Raw option is checked on the SendGrid inbound configuration and are named for backwards compatability
Example (ParseHeaders) ¶
headers := `
Foo: foo
Bar: baz
`
email := ParsedEmail{
Headers: make(map[string]string),
Body: make(map[string]string),
Attachments: make(map[string][]byte),
rawRequest: nil,
}
email.parseHeaders(headers)
fmt.Println(email.Headers["Foo"])
fmt.Println(email.Headers["Bar"])
Output: foo baz
Example (ParseRawEmail) ¶
rawEmail := `
To: test@example.com
From: example@example.com
Subject: Test Email
Content-Type: multipart/mixed; boundary=TwiLIo
--TwiLIo
Content-Type: text/plain; charset=UTF-8
Hello Twilio SendGrid!
--TwiLIo
Content-Type: text/html; charset=UTF-8
Content-Transfer-Encoding: quoted-printable
<html><body><strong>Hello Twilio SendGrid!</body></html>
--TwiLIo--
`
email := ParsedEmail{
Headers: make(map[string]string),
Body: make(map[string]string),
Attachments: make(map[string][]byte),
rawRequest: nil,
}
if err := email.parseRawEmail(rawEmail); err != nil {
log.Fatal(err)
}
for key, value := range email.Headers {
fmt.Println(key, value)
}
fmt.Println(email.Body["text/plain; charset=UTF-8"])
Output: To test@example.com From example@example.com Subject Test Email Content-Type multipart/mixed; boundary=TwiLIo Hello Twilio SendGrid!
func Parse ¶
func Parse(request *http.Request) (*ParsedEmail, error)
Parse parses an email using Go's multipart parser and populates the headers, and body This method skips processing the attachment file and is therefore more performant
func ParseWithAttachments ¶
func ParseWithAttachments(request *http.Request) (*ParsedEmail, error)
ParseWithAttachments parses an email using Go's multipart parser and populates the headers, body and processes attachments
func (*ParsedEmail) Validate ¶
func (email *ParsedEmail) Validate(config ...ValidateConfig) error
Validate validates the DKIM and SPF scores to ensure that the email client and address was not spoofed
type ValidateConfig ¶
type ValidateConfig struct {
// contains filtered or unexported fields
}
ValidateConfig adds configuration options for validating a parsed email. Specifically turning DKIM as optional. DKIM validates emails in transit from tampering. However many valid email clients do not have it configured SPF could potentially be added but it poses a more significant security risk
func NewValidateConfig ¶
func NewValidateConfig() ValidateConfig
NewValidateConfig returns a configuration struct for validating the parsed email. Specifically turning DKIM as optional. DKIM validates emails in transit from tampering. However many valid email clients do not have it configured
func (ValidateConfig) WithDKIMOptional ¶
func (vc ValidateConfig) WithDKIMOptional() ValidateConfig
WithDKIMOptional validates DKIM values only if they exist. This allows the inbound client to support more email clients that might not support this configuration
Source Files