Inbound Parse Webhook "attachment-info" is incorrect

[jimm-porch]

https://sendgrid.com/docs/API_Reference/Webhooks/parse.html

The documentation for attachment-info is incorrect in a couple of ways.

First it says the value associated with each attachmentX key is a "JSON string", but it is not a string, it is a JSON object.

A JSON string containing the attachmentX (see below) keys with another JSON string as the value.

Second, it says there is a field named filename

This string will contain the keys filename, which is the name of the file (if it was
provided) and type, which is the media type of the file.

Both of these do not match what SendGrid is actually sending our webhook. The keys associated with each attachment are full JSON objects (not strings), and the name is in a field called name (not filename):

{"attachment2":{"name":"image004.jpg","type":"image/jpeg","content-id":"image004.jpg@01D1E353.253DC190"},"attachment3":{"name":"image005.jpg","type":"image/jpeg","content-id":"image005.jpg@01D1E353.253DC190"},"attachment1":{"name":"~WRD000.jpg","type":"image/jpeg","content-id":"~WRD000.jpg"},"attachment4":{"name":"image006.jpg","type":"image/jpeg","content-id":"image006.jpg@01D1E353.253DC190"}}

[thinkingserious]

Hello @jimm-porch,

Thanks for your suggestion or question!

In an attempt to clear out our backlog, we are closing out issues over 90 days old. If this is still an issue, please feel free to reopen it.

Team SendGrid DX-Docs

[jimm-porch]

@thinkingserious I think the documentation could be clarified, although some points from my original message can use some updates....

Here's a recent example that we received (I've edited the filename and content ID to remove personal information but the structure is unchanged):

{"attachment1":{"filename":"Greg Brady.pdf","type":"application/pdf","content-id":"9a539b79-9759-509d-7796-5b9d6db8289f@foobar.com"}} 

Flaws in my original ticket

• Flaw 1: my original link to the documentation pointed to a page that doesn't describe the payload anymore, not sure if it ever did. This is the correct link as of today.
• Flaw 2: Regarding name and filename keys, I actually described it backwards. It looks like it actually contains filename as documented, but does not contain name. I'm not sure where my original example came from since I see my working commit from 3 days earlier that was using filename. Sorry about that.

Updated suggestion

The documentation still seems like it can be refined. Here's what it says:

A string containing the attachmentX keys with another JSON string as the value.
This string will contain the keys filename and name, which is the name of the file
(if it was provided) and type, which is the media type of the file.

• Suggestion 1: When it says "This string will contain the keys filename and name", it is not correct, since it does not include the name key.
• Suggestion 2: When it says "with another JSON string as the value", it is not correct, since the value is a JSON object, not a JSON string.

I would propose replacing the above with something like the following, and an actual example JSON blob.

A JSON map where the keys are named attachment{X}. Each attachment key points to
a JSON object containing three fields, filename, type, and content-id.
The filename field is the name of the file (if it was provided).
The type field is the media type of the file.

etc. I'll reopen the ticket.

[jimm-porch]

@thinkingserious Github doesn't allow me to reopen a ticket that was closed by someone else. Should I create a new more-focused ticket?

[kevinquinnyo]

Sorry to jump into an old issue, but I have scoured the docs trying to find an example of the raw JSON for a parsed email (with attachments preferably). While I'm waiting on my DNS record changes, I'd like to go ahead and get started on writing code.

Suggestion: A simple example of the full JSON response body of a raw email, as it would be posted to the webhook URL would be helpful. If this already exists and I couldn't find it, consider making it easier to find. Thanks!

edit: In case anyone finds this and wants a sample I was able to locate one.

{
    "headers":"Received: by 127.0.0.1 with SMTP id PJrfql0ZL0 Fri, 20 Sep 2013 19:20:39 +0000 (UTC)\nReceived: from mail-we0-f172.google.com (mail-we0-f172.google.com [74.125.82.172]) by mx2.sendgrid.net (Postfix) with ESMTPS id 13B2517816F3 for <reply@m.carve.io>; Fri, 20 Sep 2013 19:20:38 +0000 (UTC)\nReceived: by mail-we0-f172.google.com with SMTP id w61so926388wes.17 for <reply@m.carve.io>; Fri, 20 Sep 2013 12:20:38 -0700 (PDT)\nDKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=sendgrid.com; s=ga1; h=mime-version:date:message-id:subject:from:to:content-type; bh=Ro5Qjl2jqmXMd5jxz2Zo0og3kS5R8vkDAXec/s6jbZc=; b=ImcNYp/9fqCRNfr5MgZiWcmhfIvyvBlhXxZPwtm/Xi+o5XhiEzAXN9ZhAXLhj0jQtv PpLHqmaanVFaWyB8G+cE/3XNKiinEnk4fo456gfz/mkwGYxJ3AkH8irsmdE0y/fLAaYn Uh4uP4ZQEbVMNBsp9KXUfSzKf4mmuE8vBaB3M=\nX-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:date:message-id:subject:from:to :content-type; bh=Ro5Qjl2jqmXMd5jxz2Zo0og3kS5R8vkDAXec/s6jbZc=; b=OtJL7xC6jND+fxGy5W426hMfn6Tp1jMLuxRWjFCADu6vH3I2R1+fP4BkOtE/uqsDqF gI6njLfKtnfNI588sD0NO034TIyOMMdmgjSoR1IeU0Mv8g9WfrYyIIk4wtd+pVDs8DVe SdU+qBp1jppCtXH+lLUp7a/u8Yvmz2y6Wphb7a+YT2AACcbnkFtcw85NvOEnrqnhZvB0 Br5oTjSW7FQhzjbJWVRdLjJ0LV/B/+8KzJ46YFzUwgD5Qv31Z6NtZdq8Z5fuG3b3Pl9H MQZ/HEYBWNRdUOnkGXC+D0IYB9v9KrxG92Ep0JExdsCBOnoLPJnyLAAcjtRAQQDsaoT+ TOjg==\nX-Gm-Message-State: ALoCoQmaVX6v8md4PTHH4vYRgjw8aG0k9NmU3/th8g/0cQagIpFK4twiPKJody/Vlq5duN0RbRsy\nMIME-Version: 1.0\nX-Received: by 10.180.13.174 with SMTP id i14mr3943778wic.49.1379704837618; Fri, 20 Sep 2013 12:20:37 -0700 (PDT)\nReceived: by 10.216.183.73 with HTTP; Fri, 20 Sep 2013 12:20:37 -0700 (PDT)\nDate: Fri, 20 Sep 2013 12:20:37 -0700\nMessage-ID: <CAKQBZ6=og54eMJERSDaGL9b9TngxtzVAg9DcFr4XRtgt1V43fQ@mail.gmail.com>\nSubject: Bob attached\nFrom: Scott Motte <scott.motte@sendgrid.com>\nTo: reply@m.carve.io\nContent-Type: multipart/mixed; boundary=001a11c227e8bea96404e6d590b1\n",
    "dkim":"{@sendgrid.com : fail (body has been altered)}",
    "to":"reply@m.carve.io",
    "html":"<div dir=\"ltr\">I think Bob is attached to this.</div>\n",
    "from":"Scott Motte <scott.motte@sendgrid.com>",
    "text":"I think Bob is attached to this.\n",
    "envelope":"{\"to\":[\"reply@m.carve.io\"],\"from\":\"scott.motte@sendgrid.com\"}",
    "attachments":"1",
    "subject":"Bob attached",
    "attachment-info":"{\"attachment1\":{\"filename\":\"IMG_0768.JPG\",\"name\":\"IMG_0768.JPG\",\"type\":\"image/jpeg\"}}",
    "charsets":"{\"to\":\"UTF-8\",\"html\":\"ISO-8859-1\",\"subject\":\"UTF-8\",\"from\":\"UTF-8\",\"text\":\"ISO-8859-1\"}",
    "SPF":"pass",
    "attachment1":{
        "originalFilename":"IMG_0768.JPG",
        "path":"/tmp/2-w6psz.JPG",
        "headers":{
            "content-disposition":"form-data; name=\"attachment1\"; filename=\"IMG_0768.JPG\"",
            "content-type":"image/jpeg"
        },
        "size":80180,
        "name":"IMG_0768.JPG",
        "type":"image/jpeg"
    }
}

I found this linked https://github.com/sendgrid/sendgrid-parse-api-example in a gist url, but had to change the username in the gist as the user has changed.

If this is still accurate, consider adding it to the docs somewhere for developers who want to get started with unit tests and such without having to do all of the administration and waiting for DNS records.

[apigirl]

thanks for the activity on this everyone! Will definitely reopen this.

[danimart1991]

I would like to take this issue.

[aroach]

@kevinquinnyo I've been working on a related project in the sendgrid-nodejs repo to create a container that is a inbound parse webhook receiver. sendgrid/sendgrid-nodejs#792

I'm not sure, but I think that repo you posted may not be relevant anymore. The current functionality that I've seen is that the Inbound Parse webhook will POST multipart form data to your endpoint. Here is how I handled it using the express-formidable middleware: https://github.com/aroach/sendgrid-nodejs/blob/a846cd8ec82c5f3deb8b4bd050dc27c496ddcff5/examples/inbound-parse-docker/app.js#L12

This is an example POST body that I saved off: https://github.com/aroach/sendgrid-nodejs/blob/inbound-parse-docker/examples/inbound-parse-docker/example-webhook-payload.txt

[aroach]

To the OP's question. The current implementation is POSTing the following:

'content-ids': '{"f_jn2hg5hz1":"attachment2","f_jn2hg5h00":"attachment1"}',

'attachment-info': '{"attachment2":{"filename":"IMG_2570.jpg","name":"IMG_2570.jpg","type":"image/jpeg","content-id":"f_jn2hg5hz1"},"attachment1":{"filename":"kaylyn-dog.jpg","name":"kaylyn-dog.jpg","type":"image/jpeg","content-id":"f_jn2hg5h00"}}',

FYI, should perhaps fix the link in the OP's question (https://sendgrid.com/docs/API_Reference/Webhooks/inbound_email.html) goes into an endless redirect if it's available elsewhere on the web.

I don't actually see example payload in the latest documentation.

I think both suggestion1 and 2 are still valid and should be accepted with the addition that name is also part of the JSON map:

A JSON map where the keys are named attachment{X}. Each attachment key points to a JSON object containing three fields, filename, name, type, and content-id. The filename field is the name of the file (if it was provided). The type field is the media type of the file.