Property width

Inside an image block, you can optionally specify the width of the image. This allows you to make the image smaller than the container that it is placed in. If you do not set the width, the image will be shown in it's actual width, up to the size of the container in which it is placed. Images in an email will never become bigger than the container they are placed in, even if the real image file is bigger than the available space. This means that an image in an email can never exceed 580 pixels, because that it the max size of the email content. Images inside columns have even a smaller max width.

The width can either be set as a relative width, using a percentage value, or as an absolute width in pixels. However, internally the ResponsiveEmail API only works with percentages. The reason for this is that emails generated by ResponsiveEmail.com have to be compatible with many different devices, and images and content are supposed to scale if the device size changes (for example, if a phone or tablet is rotated, and switches between portrait and landscape mode) the images should scale too. This only works for images with a relative size.

Under the hood, if you set the image width in pixels, we convert the absolute values into relative percentages. This ensures that the images are correctly rendered on both small and normal devices. It therefore is better to use percentages when you set the width of an image in the input, although it is perfectly valid to use pixel values too.

Using percentages

If you use a relative width (a percentage value) the image will only take up a relative part of the container. Thus, if you only want your image to take up one third of the container in which it is placed, you can set the width to 33%:

{
    "subject" : "Example email",
    "from" : "info@example.com",
    "blocks" : [ {
        "type" : "image",
        "src" : "http://www.example.com/logo.png",
        "width" : "33%"
    }, {
        "type" : "html",
        "source" : "<p>Here comes all the text</p>"
    } ]
}

In the above example, the image will take up one third of the total width the mail. Be aware that this is true for all devices! Even on small mobile devices, the image will only take up one third of the available screen width.

We can imagine that you want a different behavior for your email. For example, on a normal/big device you'd like to show the logo in the left top corner of your mail, taking up one third of the available width, but on small devices you'd like to use the full device width. This is possible, but you should not use the image width property for it, but use columns instead. Columns are automatically placed under each other when a device is too small to display them next to each other:

{
    "subject" : "Example email",
    "from" : "info@example.com",
    "blocks" : [ {
        "type" : "columns",
        "columns" : [ {
            "size" : 4,
            "blocks" : [ {
                "type" : "image",
                "src" : "http://www.example.com/logo.png"
            } ],
            "size" : 8
            } , {
            "blocks" : []
        } ]
    }, {
        "type" : "html",
        "source" : "<p>Here comes all the text</p>"
    } ]
}

The example above shows an email that splits the top of the contents into two columns. Because ResponsiveEmail.com uses a 12 columns wide fluid grid system, we have created one column that is 4 units wide (one third of the email), and another column that takes up 8 units (the other two thirds). In the small first column, we have placed an image, and the wider second has been left empty. Under the two columns we have added the textual content that is going to take up all the available width.

On normal desktop devices, the two columns in the above email are going to be rendered next to each other, and the logo will take up one third of the mail width. On small devices however, the columns will be displayed above eachother, and the image takes up 100% of the device width. Below the image, the second column is shown, but because it is an empty column, it is as if nothing is displayed there. The text starts under the logo.

Using pixels

Let's get back to setting the image width. As we've explained above, the preferred way of setting an image width is to use a relative value. However, you can also specify the width of images in pixels. This may be more convenient, and the ResponsiveEmail API will turn these pixel values into percentages anyway.

Note that an image can never take up more space than the total width of the container it was placed in. Setting the width to a value of, for example, 1000 pixels is therefore pointless, because an email will never exceed the width of 580 pixels. The ResponsiveEmail API takes care of this conversion, images that are too big are automatically scaled down.

If you set the width to less pixels than the block width, the ResponsiveEmail API will calculate the relative width and use that in the generated HTML code. For example, if you place an image on top of an email, and set it's width to 290 pixels (which is exactly half of the available 580px pixels), the image will automatically take up half of the email width. Watch out: this means that the image will thus also take up half of the email on small devices, even if that means that the image would then be much smaller than 290 pixels!

{
    "subject" : "Example email",
    "from" : "info@example.com",
    "blocks" : [ {
        "type" : "image",
        "src" : "http://www.example.com/logo.png",
        "width" : "290px"
    } ]
}

For images used inside columns, the conversion to a relative width is also done, but of course then it is based on the width of the specific column, and not on the full 580px wide email content.

Not setting a width

If you do not set the width of an image, which is the default, the ResponsiveEmail.com service will try to find out for itself what the image width is by downloading the image. It will then turn this image width into a relative width, just as if you had specified the width in pixels.

To help performance, it is a good idea to always include a relative width so that no download is necessary.

Scaling

An image is automatically scaled so that the ratio between the width and height always stays the same. In normal circumstances there is no need to set the image height. If you set the height property your images may be stretched, and the width to height ratio may change.