{ "openapi": "3.0.1", "info": { "title": "SigParser Stateless Email Parsing APIs", "description": "\r\n\r\nHow to use? You can either invoke the APIs directly from your preferred language. Or you can use one of the connectors like Zapier or Integromat which makes integration much easier. \r\n\r\nAuthentication: Add a header for 'x-api-key' to each request for parsing emails with the value of your SigParser key. You can create a free key for a few uses each day at https://sigparser.com. \r\n\r\nYou can test your API key and calls with this page. Click the 'Authorize' button on the right to set your key for requests. Then click on one of the requests you want to make and set the JSON if required.\r\n\r\nIf you have any questions email support@sigparser.com.\r\n", "version": "v1" }, "paths": { "/api/Email": { "post": { "tags": [ "Email" ], "summary": "Parse an email for contacts from the signatures or remove signatures from an email. Can handle parsing contacts from a reply chain. Can also indicate if this email is likely a spam (non-human) type contact.", "requestBody": { "description": "", "content": { "application/json-patch+json": { "schema": { "$ref": "#/components/schemas/EmailParsingAPI.EmailInputModel" } }, "application/json": { "schema": { "$ref": "#/components/schemas/EmailParsingAPI.EmailInputModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/EmailParsingAPI.EmailInputModel" } }, "application/*+json": { "schema": { "$ref": "#/components/schemas/EmailParsingAPI.EmailInputModel" } } } }, "responses": { "200": { "description": "Returns JSON for the contact data.", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/EmailParsingAPI.Models.Email.FullAPIOutputModel_LegacyCase" } }, "application/json": { "schema": { "$ref": "#/components/schemas/EmailParsingAPI.Models.Email.FullAPIOutputModel_LegacyCase" } }, "text/json": { "schema": { "$ref": "#/components/schemas/EmailParsingAPI.Models.Email.FullAPIOutputModel_LegacyCase" } } } }, "403": { "description": "Some sort of API key error." }, "500": { "description": "There was an error while processing this email. Most likely you didn't provide a value we needed. This isn't an API Key error." } } }, "get": { "tags": [ "Email" ], "summary": "A testing method to validate connectivity to the API. Useful for Zapier or other integration providers to validate connectivity with no inputs.", "responses": { "200": { "description": "Success", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/EmailParsingAPI.Controllers.EmailController+GetResponseModel" } }, "application/json": { "schema": { "$ref": "#/components/schemas/EmailParsingAPI.Controllers.EmailController+GetResponseModel" } }, "text/json": { "schema": { "$ref": "#/components/schemas/EmailParsingAPI.Controllers.EmailController+GetResponseModel" } } } } } } }, "/api/Mime/ParseString": { "post": { "tags": [ "Mime" ], "summary": "Post the MIME encoded email text in the body to this API. If you have EML files then you need to post the contents of the EML file.", "responses": { "200": { "description": "Success", "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/SigParser.EmailParsing.Models.CleanedBodyOutput" } }, "application/json": { "schema": { "$ref": "#/components/schemas/SigParser.EmailParsing.Models.CleanedBodyOutput" } }, "text/json": { "schema": { "$ref": "#/components/schemas/SigParser.EmailParsing.Models.CleanedBodyOutput" } } } } } } } }, "components": { "schemas": { "EmailParsingAPI.Controllers.EmailController+GetResponseModel": { "type": "object", "properties": { "apiKeyPrefix": { "type": "string", "description": "The prefix for the API key. Just a nice util method for apps like Zapier to confirm connectivity and get an ID of some sort back.", "nullable": true } }, "additionalProperties": false }, "EmailParsingAPI.EmailInputModel": { "required": [ "from_address" ], "type": "object", "properties": { "subject": { "type": "string", "description": "Email subject. Not required but should be provided in order to have the \"subject\" field populated in the response for the \"emails\" collection.", "nullable": true }, "from_address": { "type": "string", "description": "The sender of the email. Required for us to match the contact data we find in the root email's signature with an email address." }, "from_name": { "type": "string", "description": "The sender of the email. Important to provide as it helps to identify where the signature starts although sometimes we can find the signature without it.", "nullable": true }, "htmlbody": { "type": "string", "description": "Either provide this or the PlainBody or both. This will be used for the email content over the plain body as the HTML is how we can get LinkedIn URLs and Twitter URLs for example.", "nullable": true }, "plainbody": { "type": "string", "description": "If there isn't an HTML body we'll fallback to this value. If all you can provide is a text body then we can still find phone numbers, titles and addresses but features like LinkedIn URLs and Twitter URLs embedded in HTML won't be discoverable.", "nullable": true }, "date": { "type": "string", "description": "A Date string. For example: 2017-01-01T00:00:00 OR Mon, 28 May 2018 23:33:40 +0000 (UTC)\r\nIf either of the two above formats don't match what you're providing, we fallback to using the standard .NET parsing to parse this date so you can test that your date works with DotNetFiddle. https://dotnetfiddle.net/sJyTJW", "nullable": true }, "to": { "type": "array", "items": { "$ref": "#/components/schemas/EmailParsingAPI.EmailRecipient" }, "nullable": true }, "cc": { "type": "array", "items": { "$ref": "#/components/schemas/EmailParsingAPI.EmailRecipient" }, "nullable": true }, "options": { "$ref": "#/components/schemas/EmailParsingAPI.OutputOptions" } }, "additionalProperties": false, "description": "Input model for an email to parse content from." }, "EmailParsingAPI.EmailRecipient": { "type": "object", "properties": { "name": { "type": "string", "description": "The displayname for the recipient. Should come from the email headers with each email address.", "nullable": true }, "emailAddress": { "type": "string", "description": "Email address of the recipient", "nullable": true } }, "additionalProperties": false }, "EmailParsingAPI.Models.Email.AddressParts": { "type": "object", "properties": { "street": { "type": "string", "description": "Best guess at the street part of the address", "nullable": true }, "city": { "type": "string", "description": "Best guess at the city part of the address", "nullable": true }, "state": { "type": "string", "description": "Best guess at the state/region part of the address", "nullable": true }, "postalCode": { "type": "string", "description": "Best guess at the potal code part of the address.", "nullable": true }, "country": { "type": "string", "description": "Best guess at the country part of the address.", "nullable": true } }, "additionalProperties": false }, "EmailParsingAPI.Models.Email.ContactModel": { "type": "object", "properties": { "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "emailAddress": { "type": "string", "description": "The email address for the contact.", "nullable": true }, "emailAddressDomain": { "type": "string", "description": "The domain part of the email address for a contact.", "nullable": true }, "emailAddressDomainWithoutTLD": { "type": "string", "description": "The email address domain without the TLD. Sometimes this is okay to use as the name of an organization or account in a CRM.\r\nIf the emailAddress is \"john@example.co.uk\" then this will be \"example\".\r\nIf the emailAddress is \"john@mail.example.com\" then this will be \"mail.example\".", "nullable": true }, "phoneNumber": { "type": "string", "nullable": true }, "mobilePhone": { "type": "string", "nullable": true }, "voipPhone": { "type": "string", "description": "Any Voice over IP or Whatsapp type number is placed here.", "nullable": true }, "officePhone": { "type": "string", "nullable": true }, "fax": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "addressParts": { "$ref": "#/components/schemas/EmailParsingAPI.Models.Email.AddressParts" }, "title": { "type": "string", "nullable": true }, "twitterUrl": { "type": "string", "nullable": true }, "twitterHandle": { "type": "string", "nullable": true }, "linkedInUrl": { "type": "string", "nullable": true }, "linkedInHandle": { "type": "string", "nullable": true }, "companyName": { "type": "string", "description": "Company name found in either the signature or looked up from a database of companies based on the domain name.\r\nMost of the time we get this from the signature.", "nullable": true }, "website": { "type": "string", "description": "The website from the email signature's text. This does not include the URLs in the HTML links because those are often link tracked and so they don't point to the correct domain.\r\nThe values in this field often formatted with captialization but there is no formatting guarantee.\r\nFor example, you could get \"https://www.example.com\" or \"Example.com\" or \"WWW.EXAMPLE.COM\" are all possible.", "nullable": true }, "nameSource": { "type": "string", "description": "How did SigParser determine the name for this contact? \r\nRootHeader - Came from the header of the email. This is as good as it gets generally.\r\nInlineHeader - From: John Smith (jsmith@example.com)\r\nSignature - We extracted it from the signature in the body of the email. This is a bit iffy.\r\nEmailAddressDerived - Only when the name was derived by splitting the email address from \"john.smith@example.com\" for example to get John Smith\r\nEmailAddress - The name is literally just the left section of the email address before the @ symbol.", "nullable": true }, "nameQuality": { "type": "integer", "description": "A numeric representation of the NameSource property. The lower the value, the better the name in our opinion.\r\nIf you're trying to build a contact database with SigParser's results, if in one email you get a name with a quality \r\nof 10 but then later you get a quality of 0, you should use that name. But if it was the opposite, you shouldn't overwrite\r\na 0 quality name with a 10 quality name.", "format": "int32" }, "isSpammy": { "type": "boolean", "description": "Is the email address spammy looking like no-reply@example.com or info@example.com or orders@example.com" } }, "additionalProperties": false }, "EmailParsingAPI.Models.Email.FullAPIOutputModel_LegacyCase": { "type": "object", "properties": { "error": { "type": "string", "nullable": true }, "isSpammyLookingEmailMessage": { "type": "boolean", "description": "Does this message looks like it was likely some sort of automated email. For example, does it have an \"unsubscribe\" link in it?" }, "isSpammyLookingSender": { "type": "boolean", "description": "Does the \"From\" email address look like it is a non-human type sender." }, "isSpam": { "type": "boolean", "description": "Are either IsSpammyLookingSender or IsSpammyLookingEmailMessage true." }, "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/EmailParsingAPI.Models.Email.ContactModel" }, "description": "All the contacts we found in the email and any data we found with them. Most of the time these will be from reply chains where we find a signature for someone deep in a reply chain.", "nullable": true }, "from_LastName": { "type": "string", "description": "Last name of the sender.", "nullable": true }, "from_FirstName": { "type": "string", "description": "First name of the sender.", "nullable": true }, "from_Fax": { "type": "string", "nullable": true }, "from_Phone": { "type": "string", "nullable": true }, "from_Address": { "type": "string", "description": "Whatever address SigParser found for the contact.", "nullable": true }, "from_AddressParts": { "$ref": "#/components/schemas/EmailParsingAPI.Models.Email.AddressParts" }, "from_Title": { "type": "string", "nullable": true }, "from_MobilePhone": { "type": "string", "nullable": true }, "from_OfficePhone": { "type": "string", "nullable": true }, "from_LinkedInUrl": { "type": "string", "nullable": true }, "from_TwitterUrl": { "type": "string", "nullable": true }, "from_TwitterHandle": { "type": "string", "nullable": true }, "from_EmailAddress": { "type": "string", "nullable": true }, "from_EmailAddressDomain": { "type": "string", "description": "The domain part of the email address. For example, for the email address \"john@example.com\" then this would be\r\nset to \"example.com\".", "nullable": true }, "from_EmailAddressDomainWithoutTLD": { "type": "string", "description": "The email address domain without the TLD. Sometimes this is okay to use as the name of an organization or account in a CRM.\r\nIf the emailAddress is \"john@example.co.uk\" then this will be \"example\".\r\nIf the emailAddress is \"john@mail.example.com\" then this will be \"mail.example\".", "nullable": true }, "from_LinkedInHandle": { "type": "string", "nullable": true }, "from_CompanyName": { "type": "string", "description": "Company name found in either the signature or looked up from a database of companies based on the domain name.\r\nMost of the time we get this from the signature.", "nullable": true }, "from_Website": { "type": "string", "description": "The website from the email signature's text. This does not include the URLs in the HTML links because those are often link tracked and so they don't point to the correct domain.\r\nThe values in this field often formatted with captialization but there is no formatting guarantee.\r\nFor example, you could get \"https://www.example.com\" or \"Example.com\" or \"WWW.EXAMPLE.COM\" are all possible.", "nullable": true }, "emails": { "type": "array", "items": { "$ref": "#/components/schemas/EmailParsingAPI.Models.Email.SubEmail" }, "nullable": true }, "duration": { "type": "number", "description": "Duration of email processing in milliseconds.", "format": "double" }, "cleanedemailbody": { "type": "string", "description": "The body text of the root email without the email signature or any of the email chains that might have been in the original email body.\r\nUseful for cleaning up an email for display in application UIs.", "nullable": true }, "cleanedemailbody_ishtml": { "type": "boolean", "description": "Is the cleanedemailbody HTML or Text only." }, "cleanedemailbody_plain": { "type": "string", "description": "The email body as plain text. Will always be populated. If the original HTML was email then this is that email converted to plain text with all HTML removed.", "nullable": true }, "emailTypes": { "type": "array", "items": { "type": "string" }, "description": "We can add new types of emails at any time. So be prepared to handle that.\r\nNormalEmail - A normal email.\r\nMeetingNotification - A meeting invite type email. Generally auto generatee by Google. We don't parse these.\r\nBouncedNotification - Response from an email server indicating the email was bounced.\r\nZenDeskSupportChain - Discovered a ZenDesk support email chain. SigParser can't parse these because their headers aren't well formed.", "nullable": true } }, "additionalProperties": false, "description": "This exists in order to keep the legacy casing behavior working and get the Swagger documentation casing to be right." }, "EmailParsingAPI.Models.Email.Recipient": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the person. If not on the root email, then this was parsed from the inline email headers.", "nullable": true }, "emailAddress": { "type": "string", "description": "Email address of the person. If not on the root email, then this was parsed from the inline email headers.", "nullable": true } }, "additionalProperties": false }, "EmailParsingAPI.Models.Email.SubEmail": { "type": "object", "properties": { "from_EmailAddress": { "type": "string", "description": "Email address of the sender of this email section.", "nullable": true }, "from_Name": { "type": "string", "description": "Name of the sender.", "nullable": true }, "textBody": { "type": "string", "description": "The email lines of this email without headers. Will always be populated. If the original email was HTML then this will have that HTML converted to plain text.", "nullable": true }, "htmlLines": { "type": "array", "items": { "type": "string" }, "description": "The lines of the email as HTML. You won't find all the HTML of the email here but just the HTML for the line. This helps find images and text. If you want our best approximation of the orignal email HTML, use the htmlBody field.", "nullable": true }, "date": { "type": "string", "description": "The first email's date is whatever was passed into the API. All the other emails are parsed from the email headers but aren't always parsed correctly due to the many variations in formatting clients use.", "format": "date-time", "nullable": true }, "didParseCorrectly": { "type": "boolean", "description": "Does SigParser think this email was parsed correctly? Sometimes the email headers get messed up and so if SigParser detects something weird \r\nwith what it found this will be set to false." }, "to": { "type": "array", "items": { "$ref": "#/components/schemas/EmailParsingAPI.Models.Email.Recipient" }, "nullable": true }, "cc": { "type": "array", "items": { "$ref": "#/components/schemas/EmailParsingAPI.Models.Email.Recipient" }, "nullable": true }, "htmlBody": { "type": "string", "description": "SigParser's attempt at producing an HTML email body for just this email or reply chain email. Only produced if the original email was HTML.\r\nWill not include the reply headers like \"From\" and \"To\" or \"Email sent from...\". Email signature is not stripped out. Cannot handle emails with\r\nnamespaces in the HTML which is rare but can happen. In cases where the email can't be parsed, the original full HTML will be included in the first section.", "nullable": true }, "spammyLookingEmail": { "type": "boolean" }, "subject": { "type": "string", "description": "The subject of the email or nested email. This isn't always available for every nested email.\r\nFor example, Gmail will format replies like \"On 1/1/2019 John Smith wrote:\" so there isn't a subject. But when Gmail forwards an email or\r\nOutlook replies it will have a Subject injected so you can see at each level of the reply chain what it was. Will be null if no subject is available.", "nullable": true }, "cleanedBodyHtml": { "type": "string", "description": "HTML section of the email with the signature lines removed. The Head tag may still be present so you can format the email properly.", "nullable": true }, "cleanedBodyPlain": { "type": "string", "description": "Plain text section of the email with the signature lines removed. Links are removed. If you need links, you should convert the HTML version to text and figure out how to preserve the links or HTML as needed.", "nullable": true }, "emailTypes": { "type": "array", "items": { "type": "string" }, "description": "We can add new types of emails at any time. So be prepared to handle that.\r\nNormalEmail - A normal email.\r\nMeetingNotification - A meeting invite type email. Generally auto generatee by Google. We don't parse these.\r\nBouncedNotification - Response from an email server indicating the email was bounced.\r\nZenDeskSupportChain - Discovered a ZenDesk support email chain. SigParser can't parse these because their headers aren't well formed.", "nullable": true } }, "additionalProperties": false }, "EmailParsingAPI.OutputOptions": { "type": "object", "properties": { "outputCleanedEmailHtmlDepth": { "type": "integer", "description": "Performance setting (default 1): Control to what depth the fields cleanedemailbody, emails.cleanedBodyHTML are generated with HTML.\r\n \r\nGenerating these fields can be expensive so this is meant to help improve performance for some customers that don't need these fields.\r\n \r\n0 would mean no HTML output. 1 would mean only the root email gets a cleaned version. 2 means the root email and the next previous email in the chain.\r\n \r\nThe plain text versions will still be set.\r\n \r\nIf you don't ever need the data in these fields then set to 0 to get a slightly faster average response.", "format": "int32" } }, "additionalProperties": false }, "SigParser.EmailParsing.EmailType": { "enum": [ "NormalEmail", "MeetingNotification", "BouncedNotification", "ZenDeskSupportChain", "SecureMessage" ], "type": "string" }, "SigParser.EmailParsing.Models.CleanedBodyOutput": { "type": "object", "properties": { "CleanedBodyPlain": { "type": "string", "description": "The email with the signature and reply chains removed. If the email was originally HTML then this is the HTML converted to text.", "nullable": true }, "CleanedBodyHtml": { "type": "string", "description": "The body of the email.", "nullable": true }, "IsSpammyLookingEmailMessage": { "type": "boolean", "description": "Is this email a spammy looking message or a non-human type sender. You likely don't want to use the CleeanedBody fields when rendering this message but you could if you wanted to." }, "IsSpammyLookingSender": { "type": "boolean", "description": "Does the sender of this message look like they're a spammer." }, "EmailTypes": { "type": "array", "items": { "$ref": "#/components/schemas/SigParser.EmailParsing.EmailType" }, "description": "The known type of email that this is. Useful for determining how you want to display this in a user interface.", "nullable": true }, "Emails": { "type": "array", "items": { "$ref": "#/components/schemas/SigParser.EmailParsing.Models.Email" }, "description": "Collection of all the emails extracted from the body. The first email is the most recent and the last one is the oldest. The parse quality drops off the deeper you go though since there is a bigger chance for corrupted headers.", "nullable": true }, "Subject": { "type": "string", "description": "Subject of the email as it was passed into the function or extracted from the header of the email.", "nullable": true }, "Date": { "type": "string", "format": "date-time", "nullable": true }, "Headers": { "type": "object", "additionalProperties": { "type": "string" }, "nullable": true }, "FullPlainTextBody": { "type": "string", "nullable": true }, "FullHtmlBody": { "type": "string", "nullable": true }, "MsgType": { "type": "string", "description": "Type of the .msg file.", "nullable": true } }, "additionalProperties": false }, "SigParser.EmailParsing.Models.Email": { "type": "object", "properties": { "CleanedBodyPlain": { "type": "string", "nullable": true }, "CleanedBodyHtml": { "type": "string", "nullable": true }, "Subject": { "type": "string", "nullable": true }, "Date": { "type": "string", "description": "Date is only available if it was parsed out from the email or if it was passed in for the root email.", "format": "date-time", "nullable": true }, "FromEmailAddress": { "type": "string", "nullable": true }, "FromName": { "type": "string", "nullable": true }, "To": { "type": "array", "items": { "$ref": "#/components/schemas/SigParser.EmailParsing.Models.EmailRecipient" }, "nullable": true }, "Cc": { "type": "array", "items": { "$ref": "#/components/schemas/SigParser.EmailParsing.Models.EmailRecipient" }, "nullable": true } }, "additionalProperties": false }, "SigParser.EmailParsing.Models.EmailRecipient": { "type": "object", "properties": { "Name": { "type": "string", "nullable": true }, "EmailAddress": { "type": "string", "nullable": true } }, "additionalProperties": false } }, "securitySchemes": { "api_key": { "type": "apiKey", "description": "Get this key by creating an account at www.sigparser.com/dashboard.", "name": "x-api-key", "in": "header" } } }, "security": [ { "api_key": [ ] } ] }